Python 调用 ChatGPT API 完整教程（附完整代码）

本文从零开始，手把手教你用 Python 调用 ChatGPT API，涵盖基础调用、流式输出、多轮对话、异常处理等实用场景，所有代码均可直接运行。

#Python #ChatGPT #OpenAI #API开发 #LLM应用开发

一、前置条件

1.1 Python 环境

建议使用 Python 3.8 及以上版本。通过以下命令检查：

python --version
# 或
python3 --version

1.2 安装 openai 库

OpenAI 官方维护了 Python SDK，目前主流版本是 v1.x，API 设计更现代，支持同步和异步调用。

pip install openai
# 建议固定版本，避免升级破坏接口
pip install "openai>=1.0.0"

安装完成后验证：

python -c "import openai; print(openai.__version__)"

1.3 虚拟环境（推荐）

项目开发建议使用虚拟环境隔离依赖：

python -m venv venv
source venv/bin/activate   # macOS/Linux
venv\Scripts\activate      # Windows
pip install openai

二、获取 API Key

为什么不直接用 OpenAI 官方 Key？

直接使用 OpenAI 官方 API，在国内会遇到网络访问问题。即使你有海外信用卡能注册 OpenAI 账号，在代码运行时也经常碰到连接超时。

更稳定的方式是使用国内可访问的 API 中转服务。jiekou.ai 是一个兼容 OpenAI 接口格式的中转平台，无需翻墙即可稳定调用 GPT-4o、Claude、Gemini 等模型。

获取 Key 的步骤

1. 访问 jiekou.ai 注册账号

2. 登录后进入控制台 → API Key 管理

3. 点击「新建 Key」，复制密钥

配置到环境变量（推荐）

不要把 Key 硬编码在代码里，使用环境变量更安全：

# macOS/Linux
export OPENAI_API_KEY="your-api-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY="your-api-key-here"

或者在项目根目录创建 .env 文件（记得加入 .gitignore）：

OPENAI_API_KEY=your-api-key-here

三、基础调用：单次问答

这是最简单的调用场景，发送一条消息，获取一条回复。

# basic_chat.py
import os
from openai import OpenAI

# 初始化客户端
# 使用 jiekou.ai 中转端点，国内直连无需代理
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY", "your-api-key-here"),
    base_url="https://api.jiekou.ai/v1"
)

def chat(user_message: str, model: str = "gpt-4o") -> str:
    """
    发送单条消息并获取回复
    
    Args:
        user_message: 用户输入的消息
        model: 使用的模型，默认 gpt-4o
    
    Returns:
        模型的回复文本
    """
    response = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": "你是一个有帮助的助手。"},
            {"role": "user", "content": user_message}
        ],
        temperature=0.7,    # 控制回复随机性，0-2，越低越确定
        max_tokens=1024     # 最大输出 token 数
    )
    
    return response.choices[0].message.content


if __name__ == "__main__":
    result = chat("用一句话解释什么是机器学习")
    print(result)

运行输出示例：

机器学习是让计算机通过从数据中自动学习规律，而不是依靠明确编写规则来完成任务的技术。

四、流式输出（Streaming）

当回复内容较长时，等待全部生成再显示体验很差。流式输出可以像打字机一样逐字显示，显著提升用户体验。

# stream_chat.py
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY", "your-api-key-here"),
    base_url="https://api.jiekou.ai/v1"
)

def stream_chat(user_message: str, model: str = "gpt-4o") -> str:
    """
    流式输出：边生成边打印，适合长文本场景
    
    Returns:
        完整的回复文本（同时实时打印到控制台）
    """
    full_response = ""
    
    # 设置 stream=True 开启流式模式
    stream = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": "你是一个有帮助的助手。"},
            {"role": "user", "content": user_message}
        ],
        temperature=0.7,
        stream=True   # 关键参数
    )
    
    print("助手：", end="", flush=True)
    
    for chunk in stream:
        # 每个 chunk 包含一小段文本
        delta = chunk.choices[0].delta
        if delta.content is not None:
            print(delta.content, end="", flush=True)
            full_response += delta.content
    
    print()  # 换行
    return full_response


if __name__ == "__main__":
    stream_chat("请写一首关于秋天的五言绝句，并解释其意境")

说明：

• end="" 和 flush=True 确保文字实时显示而不是缓存后一次性输出

• 循环结束后 full_response 保存了完整回复，可用于后续处理

五、多轮对话

ChatGPT API 本身是无状态的——每次请求都是独立的，不会"记住"上次说了什么。实现多轮对话的方式是手动维护 messages 历史列表，把每次的问答都追加进去。

# multi_turn_chat.py
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY", "your-api-key-here"),
    base_url="https://api.jiekou.ai/v1"
)

class ConversationChat:
    """
    支持多轮对话的聊天类
    通过维护 messages 历史实现上下文连贯
    """
    
    def __init__(self, system_prompt: str = "你是一个有帮助的助手。", model: str = "gpt-4o"):
        self.model = model
        # 初始化消息历史，包含系统提示
        self.messages = [
            {"role": "system", "content": system_prompt}
        ]
    
    def chat(self, user_message: str) -> str:
        """
        发送消息并获取回复，自动维护对话历史
        """
        # 将用户消息加入历史
        self.messages.append({
            "role": "user",
            "content": user_message
        })
        
        # 发送包含完整历史的请求
        response = client.chat.completions.create(
            model=self.model,
            messages=self.messages,
            temperature=0.7,
            max_tokens=2048
        )
        
        assistant_message = response.choices[0].message.content
        
        # 将助手回复也加入历史
        self.messages.append({
            "role": "assistant",
            "content": assistant_message
        })
        
        return assistant_message
    
    def clear_history(self):
        """清空对话历史，只保留系统提示"""
        system_prompt = self.messages[0]
        self.messages = [system_prompt]
    
    def get_history_length(self) -> int:
        """返回历史消息条数（不含系统提示）"""
        return len(self.messages) - 1


def main():
    # 创建一个专门用于 Python 教学的助手
    bot = ConversationChat(
        system_prompt="你是一个 Python 编程导师，擅长用简洁的语言解释技术概念。",
        model="gpt-4o"
    )
    
    print("多轮对话示例（输入 'quit' 退出，'clear' 清空历史）\n")
    
    while True:
        user_input = input("你：").strip()
        
        if not user_input:
            continue
        if user_input.lower() == "quit":
            break
        if user_input.lower() == "clear":
            bot.clear_history()
            print("对话历史已清空\n")
            continue
        
        reply = bot.chat(user_input)
        print(f"助手：{reply}\n")
        print(f"（当前对话轮次：{bot.get_history_length() // 2}）\n")


if __name__ == "__main__":
    main()

注意事项：

• messages 列表越长，每次请求消耗的 Token 越多，成本越高

• 长对话建议做历史截断（保留最近 N 轮）或摘要压缩

• 可以在 system 消息中设定助手的角色、风格、限制

六、异常处理与最佳实践

生产代码必须处理各种异常，不能让未捕获的错误直接崩溃：

# robust_chat.py
import os
import time
from openai import OpenAI, APIError, RateLimitError, APITimeoutError, APIConnectionError

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY", "your-api-key-here"),
    base_url="https://api.jiekou.ai/v1",
    timeout=30.0  # 设置超时时间（秒）
)

def robust_chat(user_message: str, max_retries: int = 3) -> str:
    """
    带重试机制的稳健调用
    """
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=[{"role": "user", "content": user_message}],
                temperature=0.7,
                max_tokens=1024
            )
            return response.choices[0].message.content
        
        except RateLimitError as e:
            # 触发速率限制，等待后重试
            wait_time = 2 ** attempt  # 指数退避：1s, 2s, 4s
            print(f"触发速率限制，{wait_time}s 后重试（第 {attempt + 1} 次）")
            time.sleep(wait_time)
        
        except APITimeoutError:
            print(f"请求超时，重试中（第 {attempt + 1} 次）")
            if attempt == max_retries - 1:
                raise
        
        except APIConnectionError as e:
            print(f"连接失败：{e}，请检查网络")
            raise
        
        except APIError as e:
            # 其他 API 错误（如 4xx/5xx）
            print(f"API 错误 [{e.status_code}]：{e.message}")
            if e.status_code and e.status_code < 500:
                raise  # 客户端错误不重试
    
    raise RuntimeError(f"重试 {max_retries} 次后仍然失败")


if __name__ == "__main__":
    try:
        result = robust_chat("什么是 Python 的 GIL？")
        print(result)
    except Exception as e:
        print(f"最终失败：{e}")

七、常用参数说明

• model（str）：模型名称，如 gpt-4o、gpt-4o-mini、claude-3-5-sonnet-20241022

• messages（list）：消息历史，包含 role（system/user/assistant）和 content

• temperature（float）：随机性控制，范围 0-2。0 = 确定性输出，1+ = 更有创意

• max_tokens（int）：单次回复最大 Token 数。不设置则由模型自行决定

• top_p（float）：核采样，与 temperature 类似，通常二选一调整

• stream（bool）：是否启用流式输出，默认 False

• n（int）：生成多少个候选回复，默认 1

• stop（str/list）：遇到指定字符串时停止生成

• presence_penalty（float）：降低重复话题的概率，范围 -2 到 2

• frequency_penalty（float）：降低重复词语的概率，范围 -2 到 2

Token 小贴士：

• 1 个英文单词 ≈ 1-2 个 Token

• 1 个中文汉字 ≈ 1-2 个 Token

• 可用 tiktoken 库预估 Token 数量

结语

Python 调用 ChatGPT API 并不复杂，核心就是构造 messages 列表并处理响应。掌握基础调用、流式输出和多轮对话这三个场景，已经能覆盖 80% 的实际需求。

国内开发者在接入时最常遇到的是网络问题。如果你不想折腾代理，可以直接用 jiekou.ai——兼容 OpenAI 接口格式，只需修改 base_url，支持 GPT-4o、Claude、Gemini 等多种模型，按量计费，测试成本极低。希望这篇教程能帮你快速上手，把更多时间投入到产品本身。