Python+OpenAI API：从零构建带记忆的聊天机器人实战-北京尧图网络

我第一次尝试用 Python 调用 OpenAI API 做聊天机器人的时候心态特别简单只要能发一句话过去得到一句回复就算成功了。可真上了手才发现很多教程只告诉你调用接口那三五行代码却不会告诉你上下文怎么存、超时怎么处理、密钥怎么放、参数怎么调。这篇文章我完全用自己实操的视角来讲从安装依赖开始到一个带记忆、能调参数、还能包装成 Web 接口的聊天机器人。适合刚入门 Python、想把 API 真正用起来的人。如果你已经能调通接口可以直接跳到后面看上下文管理和错误处理那部分我踩过的坑比第一行代码多得多。1. 先理清“智能”从哪来聊天机器人的最小原理1.1 别把它想成“两个人对话”本质是补全一段文本很多初学者容易把聊天机器人想复杂觉得是不是要在本地训练一个模型或者要写大量的语义分析代码。其实用 Python 和 OpenAI API 做聊天机器人我们的代码只是在做一件事把对话文本整理好交给接口然后拿到返回的文本。模型背后的“智能”来自海量语料训练出的参数而我们这边不需要理解那些参数。我用“文本接龙”来类比你给模型一句话它根据这句话预测下一个最可能出现的词然后接着预测下一个直到形成一段完整回复。所以你会发现同样一句话换个措辞结果可能差异很大因为模型是在做概率计算不是在查答案。这个认知帮我解决了很多困惑。比如有段时间我发现机器人总是“忘记”前面聊过的内容于是疯狂在代码里找状态管理的 bug。后来才反应过来模型本身没有记忆它每次能看到的只是我在 messages 数组里重新发给它的全部文本。理解了这一点后面所有上下文管理方案都是围绕“每轮请求前把该带的文本都带上”来设计的。1.2 一次调通最小请求需要理解哪些参数先给一个最小可运行代码这是整个项目的地基。新版官方 Python 库的调用方式已经统一成下面这样from openai import OpenAI client OpenAI(api_keysk-你的密钥) response client.chat.completions.create( modelgpt-3.5-turbo, messages[ {role: user, content: 你好请用一句话介绍你自己} ] ) print(response.choices[0].message.content)这段代码里有三个最关键的点。第一个是 model也就是模型名称。不同模型能力和价格差距很大刚开始不要追高选一个稳定、性价比合适的对话模型先跑通流程即可。第二个是 messages这是一个列表里面每个元素都有 role 和 content。role 表示这句话是谁说的常见的有 system、user、assistant后面会专门讲。第三个是响应结构。返回的是一个对象我们要的内容在response.choices[0].message.content里。我用过很长一段时间的旧版接口字段名是text新版统一改成了message.content。如果你以后看到老教程报类型错误多半是版本差异。1.3 OpenAI API 的计费逻辑初学阶段最容易忽略的成本聊机器人绕不开成本。OpenAI API 按 token 计费输入和输出都要收费。所谓 token简单理解就是模型处理文本的切分单位。英文里 1 个 token 通常对应 0.75 个左右单词中文比较特殊一个汉字经常被拆成 1 到 2 个 token。我见过不少人第一版代码就把所有历史对话原封不动地重复发送结果聊几十轮之后每次请求携带的文本越来越多输入 token 快速增长价格也随之变高。更麻烦的是超出模型的上下文窗口后接口会直接报错而不是自动帮你删旧内容。所以从一开始就要有成本意识模型有固定的上下文长度上限我们传给它的 messages 只是我们想让它“看到”的内容不是越多越好。后面第三部分讲的上下文管理本质上就是在成本和效果之间做平衡。2. 环境准备与密钥管理的正确姿势2.1 创建虚拟环境和安装依赖我建议任何 Python 项目都先建虚拟环境不要图省事直接装到全局。虚拟环境可以把依赖隔离在项目目录里避免不同项目的包版本互相打架。我自己有一次就是因为全局环境里的旧版 openai 库导致新代码一直报参数错误排查了半天。创建环境的命令很简单python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate激活后安装两个库就够起步pip install openai python-dotenvopenai是官方 SDKpython-dotenv用来读取密钥配置文件。版本方面只要能用OpenAI()这类新写法就是 1.x 的版本。如果安装完发现还是旧写法openai.ChatCompletion.create说明库版本太老建议升级。2.2 API Key 不该出现在代码里很多教程为了方便会把密钥直接写在代码里。跟我一样犯过这个错的人应该不少代码提交到仓库后密钥就泄露了然后被别人调用出了不少账单。正确的做法是用环境变量或者项目根目录放一个.env文件OPENAI_API_KEYsk-你的密钥然后在代码里这样读取import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY) client OpenAI(api_keyapi_key).env文件一定不要提交到代码仓库。在项目根目录建一个.gitignore把.env放进去这是最基本的自我保护。此外密钥本身是敏感凭据尽量只配最小权限不要使用超出需求的账户权限。2.3 第一次调通的最小验证脚本环境准备好之后建议先写一个最简脚本验证密钥和网络都通再开始写复杂逻辑。我的验证脚本大概长这样import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) resp client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: ping}], max_tokens10, ) print(resp.choices[0].message.content)这里故意加了一个max_tokens10一方面节省调用成本另一方面验证返回是否正常。如果报 401基本是密钥有问题如果报网络错误就先检查网络环境和连通性。这一步跑通之后后面所有代码都可以在这个脚本基础上扩展。3. 把对话历史的“记忆”交给 messages 数组3.1 role 与 messages 的结构说明messages 是聊天机器人的核心数据结构。三个最常用的 role 分别是role来源作用system开发者设定机器人的角色、性格、回复规则user用户用户输入的提问或指令assistant机器人机器人之前的回复结合一个例子看messages [ {role: system, content: 你是一个喜欢用短句回答问题的助手}, {role: user, content: 今天天气怎么样}, {role: assistant, content: 我无法获取实时天气但可以给你查天气的建议。}, {role: user, content: 那帮我查一下}, ]模型在生成下一次回复前会通读整个 messages 列表。所以 assistant 的历史回复也必须放进去否则模型不知道自己之前说过什么对话就会显得断片。记住一个原则messages 不是单次请求参数它代表你希望模型看到的完整“对话剧本”。3.2 多轮对话的两种拼接方式明白了 messages 的运行原理多轮对话实现起来就是在每次请求前追加 user 内容拿到回复后追加 assistant 内容。控制台版的循环可以这样写client OpenAI() messages [] while True: user_input input(你) if user_input.lower() exit: break messages.append({role: user, content: user_input}) response client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, ) reply response.choices[0].message.content messages.append({role: assistant, content: reply}) print(机器人, reply)这个版本虽然能跑但有个隐患messages 会无限增长。实际项目中我通常会在每次 new 请求前做一次“消息窗口管理”只保留最近的若干轮而不是全量发送。常见的做法是两种第一固定只保留最近 N 条消息第二按 token 数估算超过阈值就删最早的消息。第一种实现简单第二种更精准适合会话很长的场景。初期项目用第一种就够了MAX_ROUNDS 10 def trim_history(history): return history[-MAX_ROUNDS * 2:]这里乘 2 是因为每条会话包含 user 和 assistant 两条消息。3.3 把“记忆”截断上下文窗口管理每个模型都有最大上下文长度比如常见的对话模型能容纳的 token 数是固定的。如果你把大量历史文本都塞进去一旦超过限制接口会返回 length 错误。要精确计算 token可以用官方配套的tiktoken库import tiktoken enc tiktoken.encoding_for_model(gpt-3.5-turbo) tokens enc.encode(这是一个测试文本) print(len(tokens))不过对大多数个人项目不需要每个请求都去精确计算 token。我习惯用一个更粗的策略每次请求前把所有 messages 文本拼接起来统计大概的字符数然后按“1 个汉字约 1.5 个 token、1 个英文单词约 1.3 个 token”的经验来估算。超出预设阈值时保留 system 消息然后从最早的对话开始丢弃。这里有一个容易被坑的点system 消息最好永远放在列表第一位不要让它被当成普通历史消息删掉。我刚开始写裁剪逻辑时直接把整个列表前几项删掉结果人设消息丢了机器人的语气一下子变得很奇怪。后来才把 system 单独拆出来保护。4. 从能聊到聊得好角色设定与生成参数调优4.1 system prompt 就是产品的“人设”如果只是调通接口那聊天机器人只能算能跑离“好用”还有距离。第一个明显的提升点在 system prompt。我最早做客服 Demo 时只把用户提问放进 messages结果机器人回答风格飘忽不定有时候长篇大论有时候只回几个字。后来我在 system 里明确写了规则效果立刻稳定很多system_prompt { role: system, content: 你是一个靠谱的客服助手。语气友好但不过度热情。回答尽量控制在50字以内。如果不知道答案直接说不知道不要编造。 }这段消息并不是每一轮都由用户重复输入的但它会跟随每次请求一起发给模型。所以它相当于整个对话的“总编辑规则”设置一次就能影响后面所有回复。实际调优时可以把你想约束的行为都写进去比如用词风格、回复长度、是否允许反问、敏感问题怎么回避。4.2 temperature/top_p/max_tokens 到底影响什么生成参数是另一个能明显改变体验的地方。最常用的是 temperature它控制随机性值越低模型越倾向于选择高概率的词回答更稳定值越高输出更多样但也更容易跑偏。做客服、工具类机器人我一般设 0.2 到 0.4做创意写作、头脑风暴可以调到 0.8。top_p 是另一个采样参数和 temperature 类似表示从概率累计达到 p 的词里采样。官方文档建议不要同时大幅调整两个参数我先保持 top_p 默认主要调 temperature。max_tokens 用来限制单次回复的最大 token 数。这里要注意的是它限制的是输出长度不是思考长度。如果你的机器人需要长回答但 max_tokens 设太小句子会被硬生生切断看起来就像没说完整。我建议根据场景估算比如要输出 200 个汉字给 250 到 300 token 会比较稳。我常用的参数组合如下场景temperaturemax_tokens备注客服问答0.2150求稳闲聊机器人0.7300有点随机性文案生成0.9500接受发散4.3 流式输出从“等待十秒”到“逐字显示”第一次调用非流式接口时如果模型生成的文本很长你会明显感觉页面或终端卡住了必须等全部生成完才输出。体验很生硬。OpenAI API 支持流式返回可以把结果一点点传回来效果更接近真实打字。代码如下stream client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, streamTrue, ) for chunk in stream: delta chunk.choices[0].delta if delta.content: print(delta.content, end)注意chunk.choices[0].delta.content和普通响应里的message.content不同。很多新人第一次用流式接口时还在取message就报 AttributeError。所以看到流式输出代码一定要用对字段。流式输出除了体验更好还能让用户提前感知系统在正常响应不会以为卡死了。在 Web 场景下可以先把这些内容推到前端。5. 上线前必须处理的三类异常超时、限流、格式变动5.1 网络超时和重试不重试等于自找麻烦调用远程接口网络波动是家常便饭。第一次上线时我天真地以为公网接口会一直稳定直到某次请求卡了 30 秒后直接抛异常用户这边看到的就是机器人没反应。后来我统一给客户端设置了较长的超时时间并加了重试逻辑。新版 openai 库默认会做一定次数的重试但依赖关系多不如自己控制清晰。我常用的重试方式是捕获连接类异常和超时异常按指数退避等待import time from openai import OpenAI, APITimeoutError, APIConnectionError client OpenAI(timeout30.0) def request_with_retry(messages, retries3): for attempt in range(retries): try: response client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, ) return response except (APITimeoutError, APIConnectionError): if attempt retries - 1: raise wait 2 ** attempt time.sleep(wait)这样做的好处是第一次超时后等 2 秒再试第二次等 4 秒再试不会一失败就崩溃。不过要注意只有确认请求没有成功返回时才重试。如果请求已经到达服务端并触发了生成本由于网络原因你这边没收到响应重试就可能造成重复扣费。对普通项目来说这个概率不算高但如果做商业产品需要设计“请求 ID”之类的幂等机制。5.2 限流429与并发比想象中更容易碰到很多新人只在文档里见过“限流”直到多线程并发调用后才真正踩到。OpenAI 接口会针对并发和每时间窗口的 token 总量做限制。一旦超了就返回 429 错误。我第一次做并发测试时开了几个线程同时调用结果不断看到 RateLimitError。处理限流不能简单无脑重试因为如果是 token 配额被耗尽等几秒也不一定能恢复。我的做法分成三步第一设置单请求重试第二控制整体并发数第三对高频重复问题做缓存。简单场景里可以用信号量限制并发import threading semaphore threading.Semaphore(3) def limited_request(messages): with semaphore: response client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, ) return response如果你的机器人是单用户循环调用基本不会碰到并发限流一旦要通过 Web 服务对外提供接口并发控制就绕不开了。5.3 接口返回结构变化的防御别盲赌字段存在OpenAI SDK 返回的结构大部分时间很稳定但接口升级时偶尔有微调。我见过不止一次线上代码在取response.choices[0].message.content时写得太自信结果某一天返回里没有这句直接 KeyError 或空指针。现在我会在取结果前做一下保护msg None if response.choices and response.choices[0].message: msg response.choices[0].message.content if not msg: print(接口返回为空可能被内容过滤或参数配置导致) else: print(msg)还有一个容易被忽略的情况模型输出可能因为内容过滤而返回空字符串特别是用户输入涉及安全敏感内容时。如果直接把空字符串当成正常回答发回前端用户会以为机器人坏了。这种时候最好给一个默认兜底回复比如“这个问题我暂时无法回答”。6. 把机器人封装成 Web 接口从脚本到服务的最后一公里6.1 用 FastAPI 暴露一个 /chat 接口控制台脚本玩得差不多了下一步通常是想做一个网页版聊天界面。最省事的方案是用 FastAPI 把聊天逻辑包装成 HTTP 接口。先安装pip install fastapi uvicorn再写一个最简单的接口from fastapi import FastAPI from pydantic import BaseModel from openai import OpenAI app FastAPI() client OpenAI() class ChatRequest(BaseModel): message: str history: list[dict[str, str]] [] app.post(/chat) def chat(req: ChatRequest): messages req.history [{role: user, content: req.message}] response client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, ) reply response.choices[0].message.content return {reply: reply}这里把用户传来的历史列表直接透传没有做裁剪仅适合原型验证。生产环境里history 不应该完全由客户端决定最好在服务端按用户会话 ID 存储并且做长度限制。6.2 同步请求与异步事件循环的坑上面的代码写成def chatFastAPI 会把它放到线程池里执行不会阻塞主循环。但如果你把它改成async def chat里面又直接调用同步的client.chat.completions.create那这就会阻塞事件循环并发能力会变差。我之前第一次用 FastAPI 时就是这个原因接口看起来正常但多几个请求同时进来响应时间明显变长。正确做法是用异步客户端from openai import AsyncOpenAI from fastapi import FastAPI from pydantic import BaseModel app FastAPI() client AsyncOpenAI() class ChatRequest(BaseModel): message: str history: list[dict[str, str]] [] app.post(/chat) async def chat(req: ChatRequest): messages req.history [{role: user, content: req.message}] response await client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, ) return {reply: response.choices[0].message.content}把接口跑起来uvicorn main:app --reload如果前端页面不在本机还会遇到跨域问题。FastAPI 里加一下中间件就行from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], )注意allow_origins[*]只适合本地调试线上要收紧成你自己的域名列表。6.3 上线后我会怎么继续优化如果这个机器人要正式服务多用户我后续会优先做三件事。第一用 Redis 按用户 ID 保存历史消息把“谁聊过什么”从客户端手里收回来第二把接口改成流式响应让前端体验更好第三给每个用户加上调用频率限制防止某个用户刷爆 token 配额。除此之外日志记录也值得一开始就做好。每次请求记录模型、输入 token、输出 token、耗时、是否重试这些数据在排查问题和评估成本时特别有用。我见过一个项目上线后一直感觉费用高却分析不出原因后来加了两天日志才发现是某个循环里重复发送了整段历史。最后分享一个实操体会构建聊天机器人最大的成本不是代码而是对接口行为边界的理解。当你清楚了 messages 的构造方式、token 的计算逻辑、参数对输出的影响、异常场景的应对剩下的就是用业务逻辑把 API 组织起来。我建议你按本文顺序把最小版跑通再逐步加记忆、加参数调优、加 Web 封装。每加一层你对“智能”的掌控深一分后面遇到问题也能更快定位。

Python+OpenAI API：从零构建带记忆的聊天机器人实战

相关推荐

10月25日：Windows XP、编程语言先驱与通信巨头如何塑造计算史

lingbot-map：从原始地理数据到交互地图的加工流水线

大模型高级微调实战：从LoRA参数配置到训练评估的完整指南

更多资讯

AI芯片软硬件协同设计：六个反馈环与寄存器级实践

Zabbix运维监控平台解决方案：从部署到告警收敛的实战指南

PyFlink向量化UDF性能优化：从Arrow批传送到代码实践

AI辅助毕业论文写作完整指南：从选题到答辩的实用方法

研究生开题报告的研究内容到底写几条？科迅捷AI（官方网站：www.kexunjie.com)给出判断标准

Kubernetes探针实战：startup/liveness/readiness配置与调优

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？