OpenAI SDK 环境搭建教程
不管你后面用 LangChain / LangGraph / 原生 Agent，OpenAI SDK 都是绕不开的底座------而且国产模型（DeepSeek、Qwen、GLM）全兼容这套接口，装一次能吃遍天。
一、前置条件
-
Python ≥ 3.9（推荐 3.10/3.11，3.13 刚出部分库还没跟上）
-
一个 API Key（OpenAI 官方 / DeepSeek / 阿里百炼 / 腾讯云 AI 都行）
检查：
python --version
# 或
python3 --version二、项目初始化（建议走虚拟环境）
别全局装，踩过坑的都懂。
mkdir my_agent && cd my_agent
python -m venv .venv
# 激活
# macOS/Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate激活后命令行前面会出现 (.venv)标记，说明进沙箱了。
三、安装 OpenAI SDK
pip install --upgrade openai python-dotenv-
openai：SDK 本体 -
python-dotenv：从.env文件读 API Key，避免硬编码
💡 当前最新大版本是
openai >= 1.0（2023 年底重构过，和 0.x 旧版 API 不兼容）。如果你抄的老教程报错ChatCompletion.create() got an unexpected keyword argument...，就是版本不对。
四、配置 API Key（关键步骤）
1. 建 .env文件（千万别提交到 Git！）
touch .env.env内容：
# OpenAI 官方
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1
# 或用 DeepSeek（便宜，国内直连）
# OPENAI_API_KEY=sk-xxxxxxxxx
# OPENAI_BASE_URL=https://api.deepseek.com/v1
# 或用 Qwen（阿里百炼）
# OPENAI_API_KEY=sk-xxxxxxxxx
# OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1📌 为什么配
BASE_URL？国产模型 API 格式和 OpenAI 完全兼容，只换地址和 Key 就能用，后面代码一行不用改。
2. .gitignore别忘了
.env
.venv/
__pycache__/五、最小可运行示例
新建 main.py：
import os
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
client = OpenAI(
api_key=os.getenv("OPENAI_API_KEY"),
base_url=os.getenv("OPENAI_BASE_URL"),
)
resp = client.chat.completions.create(
model="gpt-4o-mini", # DeepSeek 换成 "deepseek-chat"
messages=[
{"role": "system", "content": "你是一个 Oracle DBA 专家"},
{"role": "user", "content": "什么场景不适合建索引？用三点说明"}
],
temperature=0.7,
max_tokens=500,
)
print(resp.choices[0].message.content)跑：
python main.py能输出 → 环境 OK。
六、几个必知的 SDK 用法
1. 流式输出（Streaming）
Agent 对话必备，不然用户干等。
stream = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "解释 Oracle GROUP BY"}],
stream=True,
)
for chunk in stream:
content = chunk.choices[0].delta.content
if content:
print(content, end="", flush=True)2. Function Calling（Agent 工具调用的根基）
tools = [{
"type": "function",
"function": {
"name": "query_oracle",
"description": "执行 Oracle SQL",
"parameters": {
"type": "object",
"properties": {
"sql": {"type": "string", "description": "SQL 语句"}
},
"required": ["sql"]
}
}
}]
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "查 emp 表 10 号部门多少人"}],
tools=tools,
)
print(resp.choices[0].message.tool_calls)3. 结构化输出（Pydantic 模式，v1.40+）
from pydantic import BaseModel
class SqlAnswer(BaseModel):
sql: str
explanation: str
resp = client.beta.chat.completions.parse(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "写一条查 10 号部门员工的 SQL"}],
response_format=SqlAnswer,
)
print(resp.choices[0].message.parsed.sql)七、国产模型对照表（BASE_URL + 模型名）
| 模型 | BASE_URL | model 名 |
|---|---|---|
| OpenAI 官方 | https://api.openai.com/v1 |
gpt-4o-mini/ gpt-4o |
| DeepSeek | https://api.deepseek.com/v1 |
deepseek-chat/ deepseek-reasoner |
| Qwen（阿里百炼） | https://dashscope.aliyuncs.com/compatible-mode/v1 |
qwen-plus/ qwen-max |
| GLM（智谱） | https://open.bigmodel.cn/api/paas/v4 |
glm-4-flash |
| 腾讯 Hunyuan | https://api.hunyuan.cloud.tencent.com/v1 |
hunyuan-lite |
八、常见报错排错
| 报错 | 原因 | 解决 |
|---|---|---|
AuthenticationError 401 |
Key 错了 / 没加载 .env |
检查 os.getenv("OPENAI_API_KEY")是否 None |
NotFoundError 404 |
model 名拼错 / base_url 不对 | 核对模型名，DeepSeek 是 deepseek-chat不是 gpt-4o |
RateLimitError 429 |
配额用完 / 新 Key 限流 | 等或换 Key |
connect timeout |
网络（OpenAI 官方需梯子） | 换国产模型或配代理 |
AttributeError: ChatCompletion.create |
openai 0.x 老版本 | pip install -U openai升到 1.x |
九、项目结构建议（从小开始）
my_agent/
├── .venv/
├── .env # Key（不上 Git）
├── .gitignore
├── requirements.txt # pip freeze > requirements.txt
├── main.py # 入口
└── agent/
├── __init__.py
├── tools.py # 工具函数
└── prompts.py # System Prompt 模板requirements.txt至少锁：
openai>=1.60
python-dotenv