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 + 模型名）

八、常见报错排错

九、项目结构建议（从小开始）

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