python包：https://pypi.org/project/openai/
openai平台：https://platform.openai.com/

安装与环境变量

pip install openai

export OPENAI_API_KEY="sk-xxx"

最小可用示例（Hello World 级）

这是你跑通 SDK 的 最小闭环代码。

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4o-mini",
    instructions="你是一个有10年经验的后端架构师",
    input="解释什么是分布式事务"
)

print(resp.output_text)

比较完整的示例

python版本：3.13.11
openai版本：>=1.6.0,<2.0.0

# agent_demo.py
"""
A minimal agent demo (2025-style OpenAI SDK).

- No LangChain
- No magic
- Pure Python
- Uses Responses API
"""

from typing import Callable
import os
from dotenv import load_dotenv
from openai import OpenAI, OpenAIError

# ------------------------------------------------------------------------------
# Bootstrap
# ------------------------------------------------------------------------------

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
if not OPENAI_API_KEY:
    raise RuntimeError("OPENAI_API_KEY is not set")

client = OpenAI(api_key=OPENAI_API_KEY)

DEFAULT_MODEL = "gpt-4o-mini"

# ------------------------------------------------------------------------------
# Local tool (mock)
# ------------------------------------------------------------------------------

def get_weather_for_location(city: str) -> str:
    """Local demo tool."""
    return f"It's always sunny in {city} (demo data)."

# ------------------------------------------------------------------------------
# LLM wrapper
# ------------------------------------------------------------------------------

def call_llm(prompt: str, model: str = DEFAULT_MODEL) -> str:
    """
    Call OpenAI via Responses API and return plain text output.
    """
    try:
        resp = client.responses.create(
            model=model,
            input=prompt,
        )
        return resp.output_text

    except OpenAIError as e:
        # 明确失败原因，方便你以后做 retry / fallback
        raise RuntimeError(f"LLM call failed: {e}") from e

# ------------------------------------------------------------------------------
# Agent
# ------------------------------------------------------------------------------

def build_agent() -> Callable[[str], str]:
    """
    Build a simple agent:
    - Detects weather questions
    - Otherwise delegates to LLM
    """
    def agent(prompt: str) -> str:
        text = prompt.lower().strip()

        if "weather in " in text:
            city = prompt.split("weather in ", 1)[-1].strip()
            return get_weather_for_location(city)

        return call_llm(prompt)

    return agent

# ------------------------------------------------------------------------------
# Manual test
# ------------------------------------------------------------------------------

if __name__ == "__main__":
    agent = build_agent()

    print(agent("What's the weather in Tokyo?"))
    print("-" * 40)
    print(agent("Explain how to deploy microservices."))

fastapi==0.95.2
uvicorn[standard]==0.22.0
python-dotenv==1.0.1
openai>=1.6.0,<2.0.0
numpy==1.26.2
scikit-learn==1.3.0

openai 不能“天然支持”所有大模型本质？

从工程角度看，openai 本质是：

一个严格绑定 OpenAI API 协议（HTTP + JSON 结构）的 SDK

比如你写的这一句：

client.responses.create(...)

背后发生的是：

POST https://api.openai.com/v1/responses
Authorization: Bearer xxx
Content-Type: application/json

{
  "model": "...",
  "input": ...
}

所以关键点是：

SDK 不关心模型“是不是 GPT”，
只关心“接口是不是 OpenAI 这一套协议”

---

一个模型要“能被 openai SDK 接入”，必须满足什么条件？

1️⃣ HTTP API 形态

• RESTful
• JSON 请求 / JSON 响应
• 支持 Authorization: Bearer xxx

---

2️⃣ 路径必须一致（或可配置）

至少要支持：

POST /v1/responses
或
POST /v1/chat/completions

---

3️⃣ 请求字段结构一致

最少要支持：

{
  "model": "xxx",
  "input": "..."
}

或：

{
  "model": "xxx",
  "messages": [...]
}

---

4️⃣ 响应结构一致

例如：

{
  "output": [
    {
      "content": [
        {"type": "output_text", "text": "..."}
      ]
    }
  ]
}

或者旧版：

{
  "choices": [
    {
      "message": { "content": "..." }
    }
  ]
}

OpenAI API = 事实上的 LLM 行业接口标准

就像：

• JDBC 是数据库标准
• POSIX 是系统接口标准
• S3 是对象存储标准

你的业务代码
   ↓
OpenAI SDK / 协议
   ↓
模型 A / 模型 B / 自建模型

👉 模型可以换，业务代码不动 模型切换只改配置

OpenAI(
    api_key=KEY,
    base_url=BASE_URL
)

国产模型如何接入openai

• 一些国产大模型的 OpenAI-compatible API
• 自建模型（vLLM / LMDeploy / TGI）开启 OpenAI 模式
• 云厂商提供的 OpenAI Proxy

改 base_url

from openai import OpenAI

client = OpenAI(
    api_key="fake-key",
    base_url="http://localhost:8000/v1"
)

resp = client.responses.create(
    model="qwen2.5-7b-instruct",
    input="解释什么是幂等性"
)

print(resp.output_text)

此时：

• SDK 还是 openai
• 模型已经不是 OpenAI 的了

Chat Completions（老接口，后面舍弃了）

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是数据库专家"},
        {"role": "user", "content": "什么是索引覆盖"}
    ]
)

print(resp.choices[0].message.content)

Embedding（RAG 必备，必须会）

文本 → 向量

emb = client.embeddings.create(
    model="text-embedding-3-large",
    input="银屑病的治疗方案有哪些"
)

vector = emb.data[0].embedding
print(len(vector))  # 通常是几千维

流式输出（Web / Chat UI 必备）

同步流式

with client.responses.stream(
    model="gpt-4o-mini",
    input="详细解释 TCP 三次握手"
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)

适用场景

• Chat UI
• 控制台实时输出
• 降低首 token 延迟

---

Async 用法

from openai import AsyncOpenAI

client = AsyncOpenAI()

async def ask_ai():
    resp = await client.responses.create(
        model="gpt-4o-mini",
        input="什么是 CAP 定理"
    )
    return resp.output_text

---

申请chatGPT的token

1、新建项目

2、新建key

key要保存好，否则无法找到

小技巧

严格输出格式

❌ 错误示例（新手最容易踩）：

"请用 JSON 输出"

✅ 正确做法：明确 Schema

resp = client.responses.create(
    model="gpt-4o-mini",
    instructions="""
你是一个 API 服务。
请严格按照 JSON 格式返回，不要输出多余文字。
""",
    input="""
用户问题：什么是缓存击穿？
返回格式：
{
  "definition": string,
  "cause": string,
  "solution": string
}
"""
)

print(resp.output_text)

• 永远假设模型会犯错
• 下游一定要 json.loads + try/catch
• 重要系统：加二次校验 / retry

---

工程级封装

# ai_client.py
from openai import OpenAI

client = OpenAI()

def llm(prompt: str) -> str:
    resp = client.responses.create(
        model="gpt-4o-mini",
        input=prompt,
        temperature=0.7
    )
    return resp.output_text

# service.py
from ai_client import llm

def explain(term: str):
    return llm(f"用通俗语言解释：{term}")

真实工程中你会这样用

用户问题
  ↓
embedding
  ↓
向量数据库相似度搜索
  ↓
取 topK 文档
  ↓
拼 prompt
  ↓
responses.create

注意：

• embedding 结果一定要缓存
• 同一句话不要反复算

---