使用 Python 接入 AI 大语言模型至个人项目

把 base_url、api_key、model 换成你的环境，即可在任意 OpenAI 兼容服务上跑起来。

2.2 客户端 OpenAI() 参数说明

OpenAI() 用于创建与 API 服务通信的客户端，常用参数如下。

示例：带超时与重试的客户端。

client = OpenAI(
    base_url="https://api.openai.com/v1",
    api_key="your-api-key",
    timeout=120.0,
    max_retries=2,
)

2.3 流式对话：chat.completions.create(..., stream=True)

流式调用时，接口返回的是一个迭代器，每次迭代得到一个「片段」对象，片段里当前新增的文本在 chunk.choices[0].delta.content。

要点：

• stream=True 必须传入，否则返回的是整段完成后再返回的单个对象，而不是迭代器。
• 每个 chunk 可能有 chunk.choices[0].delta.content 为 None（例如只更新 role 或仅心跳），所以判断后再用。
• 流式响应没有最终的 usage（部分服务在流结束前会发一个带 usage 的 chunk，需看具体实现）。

示例：流式打印并拼接完整回复。

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role":"user","content":"用三句话介绍 Python。"}],
    stream=True,
)
full = []
for chunk in stream:
    if chunk.choices and len(chunk.choices) > 0:
        delta = chunk.choices[0].delta
        if getattr(delta, "content", None):
            full.append(delta.content)
            print(delta.content, end="")
print()
reply = "".join(full)

2.4 create() 常用参数详解

client.chat.completions.create() 的常用参数如下，兼容 OpenAI 的厂商大多支持其中大部分。

示例：带温度、最大 token 和 stop 的调用。

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role":"user","content":"写一首四句诗，关于编程。"}],
    stream=False,
    temperature=0.8,
    max_tokens=200,
    stop=["。","\n\n"],
)
text = resp.choices[0].message.content

2.5 非流式调用与响应结构

当 **stream=False**（默认）时，create() 返回一个 ChatCompletion 对象，常用属性：

• id：本次完成的 ID。
• **choices**：列表，通常只有一项。choices[0].message 是助手消息；choices[0].message.content 是文本内容。
• **choices[0].finish_reason**：结束原因，如 "stop"（正常结束）、"length"（达到 max_tokens）、"tool_calls"（调用了工具）等。
• **usage**：若服务返回则有 prompt_tokens、completion_tokens、total_tokens，用于计费或统计。

示例：非流式并取完整回复与 token 数。

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role":"user","content":"1+1=?"}],
    stream=False,
)
msg = completion.choices[0].message
print(msg.content) # 助手回复文本
print(msg.role) # "assistant"
print(completion.choices[0].finish_reason) # "stop" 等
if completion.usage:
    print(completion.usage.total_tokens) # 总 token 数

2.6 消息格式 messages 与多轮对话

messages 是按顺序的对话列表，每项为 {"role": "...", "content": "..."}。

多轮对话示例：带 system，并保留一轮 user/assistant 历史。

messages = [
    {"role":"system","content":"你是一个简洁的技术助手，只回答一句话。"},
    {"role":"user","content":"Python 的 GIL 是什么？"},
    {"role":"assistant","content":"GIL 是全局解释器锁，同一时刻只允许一个线程执行 Python 字节码。"},
    {"role":"user","content":"怎么规避？"},
]
completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    stream=False,
)
print(completion.choices[0].message.content)

部分兼容 API 还支持 多模态：user 的 content 可以是数组，包含 {"type": "text", "text": "..."} 和 {"type": "image_url", "image_url": {"url": "..."}} 等，用于图文问答。

2.7 其他常用能力与函数

• 列出模型（部分服务支持）：client.models.list() 可返回可用模型列表，便于在 UI 里展示或校验 model 是否有效。
• Function Calling / Tools：在 create() 里传入 tools 和 tool_choice，模型会返回 tool_calls，你本地执行对应函数后再把结果以 role="tool" 的消息 append 到 messages 并再次调用，实现「模型决定调哪个函数、你执行并回传」的流程。
• JSON 模式：response_format={"type": "json_object"} 让模型尽量输出合法 JSON，便于解析。
• 流式中的 usage：部分厂商在流式结束时通过最后一个 chunk 的 usage 返回 token 统计，需按各服务文档处理。

这些在「最小接入」时可选；先把 create() 的 model / messages / stream 用熟，再按需加参数即可。

2.8 错误处理与重试

常见异常来自 openai 库：

• openai.APIConnectionError：网络/连接问题，可视为临时错误，适合重试。
• **openai.APIStatusError**：HTTP 状态码非 2xx，如 401（key 错误）、429（限流）、5xx（服务端错误）。可通过 e.status_code、e.message 区分是否可重试（例如 5xx 可重试，401 则不必）。

示例：捕获并区分错误。

from openai import OpenAI, APIConnectionError, APIStatusError
client = OpenAI(base_url="...", api_key="...")
try:
    stream = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role":"user","content":"Hi"}],
        stream=True,
    )
    for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")
except APIConnectionError as e:
    print("连接失败，可重试:", e)
except APIStatusError as e:
    print("API 错误:", e.status_code, e.message)
    if e.status_code and 500 <= e.status_code < 600:
        print("服务端错误，可稍后重试")

生产环境可在此基础上加指数退避重试、超时和日志（注意不要打印 api_key）。

小结第二节：用 Python 使用 AI 聊天 = 用 OpenAI(base_url=..., api_key=..., ...) 构造客户端，用 **client.chat.completions.create(model=..., messages=..., stream=True/False, ...)** 发请求；流式用迭代器取 chunk.choices[0].delta.content，非流式用 completion.choices[0].message.content。掌握 messages 格式和常用参数后，即可接入任意 OpenAI 兼容服务，并在此基础上做多模型、多轮对话和错误处理。

三、示例项目简介 📦

这是一个轻量桌面 AI 聊天应用，用 Python + CustomTkinter 编写，底层只用 openai 库的兼容接口，会话与消息存 SQLite，配置在用户目录 config.json，支持多 Provider 切换、流式对话与亮/暗主题。下面用其架构说明如何把「最小示例」扩展成可维护的完整应用。

四、整体架构：分层与职责 🏗️

示例项目采用清晰分层：UI 层（主窗口、设置）→ 应用层 AppService（会话、发消息、配置）→ 基础设施（ConfigStore、SessionRepo、MessageRepo、ChatClient）。「用 Python 接入 AI 聊天」落在 ChatClient：上层只依赖流式回调抽象，具体是否 OpenAI 兼容由 Chat 层封装。

• UI 层：只负责界面与用户操作，通过应用层发消息、改配置。
• 应用层：编排发消息、会话 CRUD、当前模型、主题，不依赖具体 UI。

基础设施：ChatClient（流式 API）、ConfigStore、SessionRepository、MessageRepository，均可替换。

五、流式发送消息的完整流程 🔄

从用户点击发送到界面逐字显示、再写入数据库：UI 将用户输入和 chunk_queue 交给 AppService；AppService 在后台线程调用 ChatClient.stream_chat(provider, messages, on_chunk)，在 on_chunk 里把片段放入队列；主线程轮询队列更新 UI；收到 DoneChunk 后把完整助手回复写入 MessageRepository。你在自己项目里也可采用：队列 + 后台线程调流式 API + 主线程消费队列更新 UI。

六、核心代码解析：Chat 抽象与 OpenAI 实现 🔧

示例项目

• 在 src/chat/client.py 定义流式片段类型（TextChunk、DoneChunk、ChatError）和抽象 ChatClient.stream_chat(provider, messages, on_chunk)；
• 在 src/config/models.py 用 Provider（id、name、base_url、api_key、model_id）表示一个模型配置；
• OpenHuluChatClient 在 src/chat/openai_client.py 里用 OpenAI(base_url=..., api_key=...) 和 chat.completions.create(..., stream=True) 实现流式回调，错误统一转为 ChatError 经 on_chunk 回传。 这样任何 OpenAI 兼容或自研实现只要实现 ChatClient 即可接入。

七、如何接入到你自己的项目 🚀

• 只想要「调用流式聊天」：复制第二节最小示例，用 OpenAI(...) + chat.completions.create(..., stream=True)；多模型可像示例一样用 Provider 存多组 base_url / api_key / model_id。
• 想要可替换的聊天实现：定义 ChatClient 抽象和 stream_chat(provider, messages, on_chunk)，当前用 OpenHuluChatClient，后续可换 Azure/自建实现并注入。
• 想要界面 + 后台线程 + 队列：主线程传 queue.Queue() 给应用层并轮询；后台线程在 on_chunk 里 chunk_queue.put(chunk)，参考示例的 AppService.send_message。
• 依赖：Python 3.10+，pip install openai>=1.0.0；配置用环境变量、JSON 或数据库均可。

八、扩展方向 📈

• 多模型/多厂商：配置多个 Provider，无需改代码。
• 换聊天实现：实现自己的 ChatClient 并注入。
• 换存储/配置：替换 ConfigStore、SessionRepository、MessageRepository。
• 打包分发：PyInstaller 打包 exe，配置与数据库放用户目录。

九、小结 ✅

• 用 Python 使用 AI 聊天模型：安装 openai，用 OpenAI(base_url=..., api_key=...) + chat.completions.create(..., stream=True/False, ...) 即可对接任意 OpenAI 兼容 服务；第二节已展开各参数、消息格式、流式/非流式与错误处理。
• 示例项目在此基础上做了多 Provider、流式对话、本地 SQLite、桌面 UI 和 ChatClient 抽象，便于复用或替换实现。
• 若只在现有项目里加「AI 对话」：从第二节最小示例起步即可；若要做成可维护应用，可参考示例的分层与流式流程，按需抽取 Chat 层与持久化层。