如何把 AI 大语言模型接入个人项目

码农葫芦侠2026-02-26 8:40

通过 Python 把 AI 大语言模型接入自己的项目

本文以开源项目 HuluAiChat 为例，说明如何用 Python 将任意「OpenAI 兼容」的 AI 聊天模型接入到自己的应用里。读完你将掌握：如何用 openai 库的每一类参数与用法、最小可运行示例、以及如何复用到你的项目中。

目录

一、为什么要自己接入 AI 聊天？ 💡

现成产品（如 ChatGPT 网页、各类 App）已经很好用，但在这些场景里你会希望把大模型能力嵌进自己的项目：

  • 桌面/Web 应用：在自有产品里提供对话能力，数据与界面完全可控。
  • 多模型与私有化：同时使用 OpenAI、国产大模型、自建或代理 API，统一一套界面与逻辑。
  • 流式体验：回复逐字输出，而不是等整段生成再显示。
  • 本地历史：会话与消息存本地，方便检索、导出或合规。

用 Python + OpenAI 兼容 API 可以很低成本地实现上述目标。下面以 「如何用 Python 调用 AI 聊天」 为核心，详解 openai 库的用法与参数，再简要结合 HuluChat 说明如何接到完整项目里。

二、用 Python 调用 AI 聊天：参数、函数与用法详解（核心） 📖

只要你的 API 是 OpenAI 兼容 的（提供 POST /v1/chat/completions，请求/响应格式一致），用官方 openai Python 库即可，无需区分具体厂商。本节是全文重点：把客户端构造、create() 参数、消息格式、流式/非流式、错误处理等讲清楚，方便你直接用到自己的项目。

2.1 安装与客户端构造

安装依赖：

bash 复制代码 
pip install openai>=1.0.0

最小示例：构造客户端并发起一次流式请求。

python 复制代码 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.openai.com/v1",  # 或你的 API 地址
    api_key="your-api-key",
)

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "用一句话介绍 Python。"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
print()

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

2.2 客户端 OpenAI() 参数说明

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

参数 类型 说明
base_url str API 根地址，如 https://api.openai.com/v1。国内/自建可填 https://api.deepseek.com/v1、https://openai.xxx.com/v1 等。不填则默认官方 OpenAI。
api_key str 对应服务的密钥。部分兼容服务允许占位符（如 dummy），但生产环境必须填有效 key。
timeout `float None`
max_retries int 失败时最大重试次数，默认 2。设为 0 可关闭自动重试。
http_client 自定义 HTTP 客户端 可注入自己的 httpx.Client，用于代理、自定义 header 等。

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

python 复制代码 
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，需看具体实现）。

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

python 复制代码 
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 的厂商大多支持其中大部分。

参数 类型 说明
model str 模型 ID，如 gpt-4o-mini、deepseek-chat、qwen-plus 等，由服务方规定。
messages list[dict] 对话历史，见 [2.6 节](#参数 类型 说明 model str 模型 ID，如 gpt-4o-mini、deepseek-chat、qwen-plus 等，由服务方规定。 messages list[dict] 对话历史，见 2.6 节。必填。 stream bool 是否流式返回。True 时返回迭代器；False 时返回一个完整 ChatCompletion 对象。 temperature float 采样随机度，范围一般 0～2。越高越随机，越低越确定。做代码/翻译时可设 0.2～0.3。 top_p float 核采样：只从概率质量前 top_p 的 token 中采样。与 temperature 二选一调即可。 max_tokens int 回复最大 token 数（部分服务用 max_completion_tokens）。不设则用模型默认上限。 stop str
stream bool 是否流式返回。True 时返回迭代器；False 时返回一个完整 ChatCompletion 对象。
temperature float 采样随机度，范围一般 0～2。越高越随机，越低越确定。做代码/翻译时可设 0.2～0.3。
top_p float 核采样：只从概率质量前 top_p 的 token 中采样。与 temperature 二选一调即可。
max_tokens int 回复最大 token 数（部分服务用 max_completion_tokens）。不设则用模型默认上限。
stop `str list[str]`
frequency_penalty float -2～2，正值减少重复，让模型少重复已出现过的词。
presence_penalty float -2～2，正值鼓励谈论新话题。
n int 同一条请求生成几条回复，默认 1。大于 1 时 choices 有多条，按需取用。
response_format dict 约束输出格式，如 {"type": "json_object"} 要求返回合法 JSON。
tools list 函数/工具列表，用于 Function Calling；与 tool_choice 配合。
seed int 固定随机种子，便于复现（部分模型支持）。

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

python 复制代码 
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 数。

python 复制代码 
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": "..."}。

role 说明
system 系统提示，设定助手身份、风格、规则。可选，多数放在第一条。
user 用户说的话。
assistant 助手之前的回复，用于多轮对话时把历史带上。

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

python 复制代码 
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 则不必）。

示例：捕获并区分错误。

python 复制代码 
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 兼容服务，并在此基础上做多模型、多轮对话和错误处理。

三、HuluAiChat 项目简介 📦

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

类别 技术
语言 Python 3.10+
界面 CustomTkinter
聊天 API openai 库（OpenAI 兼容）
持久化 SQLite
配置 用户目录 config.json
打包 PyInstaller（Windows exe）

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

HuluAiChat 采用清晰分层：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 实现 🔧

HuluAiChat

  • 在 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)；多模型可像 HuluChat 一样用 Provider 存多组 base_url / api_key / model_id。
  • 想要可替换的聊天实现 ：定义 ChatClient 抽象和 stream_chat(provider, messages, on_chunk)，当前用 OpenHuluChatClient，后续可换 Azure/自建实现并注入。
  • 想要界面 + 后台线程 + 队列 ：主线程传 queue.Queue() 给应用层并轮询；后台线程在 on_chunk 里 chunk_queue.put(chunk)，参考 HuluChat 的 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 兼容 服务；第二节已展开各参数、消息格式、流式/非流式与错误处理。
  • HuluChat 在此基础上做了多 Provider、流式对话、本地 SQLite、桌面 UI 和 ChatClient 抽象，便于复用或替换实现。
  • 若只在现有项目里加「AI 对话」：从第二节最小示例起步即可；若要做成可维护应用，可参考 HuluChat 的分层与流式流程，按需抽取 Chat 层与持久化层。

项目地址：HuluAiChat（欢迎 Star / Issue / PR）。如有问题或想交流接入方式，可在仓库提 Issue 或讨论。

相关推荐
卷福同学2 小时前
【养虾日记】Openclaw操作浏览器自动化发文
人工智能·后端·算法
春日见2 小时前
如何入门端到端自动驾驶？
linux·人工智能·算法·机器学习·自动驾驶
vistaup2 小时前
claude 任务完成通知
ai
光锥智能2 小时前
从自动驾驶到 AI 能力体系，元戎启行 GTC 发布基座模型新进展
人工智能
luoganttcc2 小时前
自动驾驶 世界模型 有哪些
人工智能·机器学习·自动驾驶
潘高3 小时前
10分钟教你手撸一个小龙虾(OpenClaw)
人工智能
禁默3 小时前
光学与机器视觉：解锁“机器之眼”的核心密码-《第五届光学与机器视觉国际学术会议(ICOMV 2026)》
人工智能·计算机视觉·光学
深小乐3 小时前
不是DeepSeek V4！这两个神秘的 Hunter 模型竟然来自小米
人工智能
laozhao4323 小时前
科大讯飞中标教育管理应用升级开发项目
大数据·人工智能
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04UV安装并设置国内源05OpenClaw Control UI安全上下文访问配置06小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）07Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services08OpenClaw macOS 完整安装与本地模型配置教程（实战版）09本地部署 OpenClaw + DeepSeek-R1 完全指南10AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南