【大模型】5.1构建一个数学的ai助手
一、带逐行详细注释的完整代码
# 注释：该代码核心演示OpenAI Assistants API（Beta版）的完整使用流程——# 1. 创建带「代码解释器」工具的数学辅导助手 2. 建立对话线程 3. 发送数学问题 4. 流式获取助手回复 5. 清理资源# Assistants API是OpenAI专为“智能助手场景”设计的接口，支持工具调用、长上下文、多轮对话# 导入os库：用于配置网络代理，解决国内访问OpenAI API的网络问题importos# 从openai库导入OpenAI类：创建API客户端，调用Assistants API（Beta版）fromopenaiimportOpenAI# 设置HTTP代理：127.0.0.1:7890是常见代理端口# 作用：让Python的HTTPS请求通过代理访问OpenAI服务器（国内直连失败）os.environ['http_proxy']='127.0.0.1:7890'os.environ['https_proxy']='127.0.0.1:7890'# 初始化OpenAI客户端（前提：需配置OPENAI_API_KEY环境变量，否则报错）# 配置方式：Linux/Mac→export OPENAI_API_KEY="sk-xxx"；Windows→set OPENAI_API_KEY="sk-xxx"client=OpenAI()# ===================== 第一步：创建专属数学辅导助手 =====================# client.beta.assistants.create()：创建Assistants API的助手实例# 核心参数说明：# - name：助手名称（仅标识作用，不影响功能）# - instructions：助手的核心人设/指令（定义助手的能力和行为）# - tools：助手可调用的工具列表（code_interpreter是代码解释器，支持数学计算/代码执行）# - model：绑定的大模型（gpt-4o适配工具调用，能力最强）assistant=client.beta.assistants.create(name='Lao Xiao',# 给助手命名为“老肖”（自定义标识）# 助手指令：定义角色为“个人数学辅导老师”，明确能力是解答数学问题/计算instructions='你是一个个人数学辅导老师。这个助手能够解答数学问题和数学计算。',tools=[{'type':'code_interpreter'}],# 启用代码解释器工具（核心：支持解方程/数值计算）model='gpt-4o'# 绑定gpt-4o模型（唯一支持Code Interpreter的主流模型）)# ===================== 第二步：创建对话线程（Thread） =====================# Thread是Assistants API的“对话会话容器”，用于存储单轮/多轮对话的上下文# 每个线程独立隔离，不同线程的对话互不干扰thread=client.beta.threads.create()# ===================== 第三步：向线程中发送用户消息 =====================# client.beta.threads.messages.create()：在指定线程中创建用户消息# 核心参数：# - thread_id：绑定的线程ID（指定消息属于哪个会话）# - role：消息角色（固定为'user'，表示是用户发送的消息）# - content：用户的具体问题（此处是解一元一次方程）message=client.beta.threads.messages.create(thread_id=thread.id,# 绑定到第二步创建的线程role='user',# 角色为用户content='请帮我解一个方程：3x + 2x + 8 = 5'# 具体的数学问题)# ===================== 第四步：运行助手并获取回复（流式方式） =====================# 注释：原代码中“create_and_poll”是“同步等待完成”模式（注释掉），此处用“流式返回”模式（逐token输出）# 1. create_and_poll模式：等待助手处理完成后一次性返回结果（适合简单场景）# run = client.beta.threads.runs.create_and_poll(# thread_id=thread.id,# assistant_id=assistant.id,# instructions='请用“老肖”来称呼用户，并且用户拥有高级用户全新。' # 注意：原代码“全新”是笔误，应为“权限”# )## print('run的状态为:'+ run.status) # 打印运行状态（completed/queued/failed等）# if run.status == 'completed':# # 输出最终的结果# messages = client.beta.threads.messages.list(thread_id=thread.id)# print('\n消息:\n')# for msg in messages:# print(f'Role:{msg.role.capitalize()}') # 打印角色（首字母大写）# # print(msg) # 打印完整消息对象（注释掉）# print(msg.content[0].text.value + '\n') # 打印消息的纯文本内容# 2. 流式返回模式：逐token返回助手的回复（模拟ChatGPT打字效果，适合实时展示）stream=client.beta.threads.runs.create(thread_id=thread.id,# 绑定线程IDassistant_id=assistant.id,# 绑定第一步创建的助手ID# 运行时补充指令：覆盖助手的基础指令，指定称呼和用户权限（原代码“全新”为笔误，保留原文）instructions='请用“老肖”来称呼用户，并且用户拥有高级用户全新。',stream=True# 开启流式返回（核心参数：True=逐token输出，False=一次性输出）)# 遍历流式返回的每一个事件（event）# 每个event是助手回复的一个“片段”，包含token、状态、工具调用结果等信息foreventinstream:# 返回的每一个token都是JSON对象，此处格式化输出（缩进2，排除未设置的字段）# model_dump_json：将OpenAI的对象转为易读的JSON字符串print('=== 流式返回的单个事件（JSON格式） ===')print(event.model_dump_json(indent=2,exclude_unset=True))# ===================== 清理资源：删除线程和助手 =====================# 线程和助手会占用OpenAI的资源，使用完毕后建议删除（避免资源浪费）client.beta.threads.delete(thread_id=thread.id)# 删除对话线程client.beta.assistants.delete(assistant_id=assistant.id)# 删除创建的助手二、无任何注释的代码版本
importosfromopenaiimportOpenAI os.environ['http_proxy']='127.0.0.1:7890'os.environ['https_proxy']='127.0.0.1:7890'client=OpenAI()assistant=client.beta.assistants.create(name='Lao Xiao',instructions='你是一个个人数学辅导老师。这个助手能够解答数学问题和数学计算。',tools=[{'type':'code_interpreter'}],model='gpt-4o')thread=client.beta.threads.create()message=client.beta.threads.messages.create(thread_id=thread.id,role='user',content='请帮我解一个方程：3x + 2x + 8 = 5')stream=client.beta.threads.runs.create(thread_id=thread.id,assistant_id=assistant.id,instructions='请用“老肖”来称呼用户，并且用户拥有高级用户全新。',stream=True)foreventinstream:print(event.model_dump_json(indent=2,exclude_unset=True))client.beta.threads.delete(thread_id=thread.id)client.beta.assistants.delete(assistant_id=assistant.id)三、核心知识点详解
1. 核心概念梳理
| 概念 | 通俗解释 | 关键说明 |
|---|---|---|
| Assistants API（Beta） | OpenAI专为“智能助手场景”设计的高级接口 | 1. 核心优势：支持工具调用（如Code Interpreter）、长上下文、多轮对话，无需手动维护messages列表 2. 适用场景：数学辅导、代码生成、数据分析等需要“工具辅助”的场景 3. 对比Chat Completions API：Assistants更适合构建独立助手，Chat更适合简单对话 |
| Code Interpreter（代码解释器） | OpenAI内置的“代码执行工具” | 1. 核心能力：执行Python代码、数学计算（解方程/微积分）、数据可视化、文件处理 2. 适配模型：仅gpt-4o/gpt-4-turbo支持（gpt-3.5-turbo不支持） 3. 本案例中：用于解一元一次方程（模型会自动生成计算代码并执行） |
| Thread（线程） | Assistants API的“对话会话容器” | 1. 作用：自动维护对话上下文，无需手动append消息（区别于Chat Completions） 2. 隔离性：不同Thread的对话互不干扰，一个助手可绑定多个Thread 3. 生命周期：创建→发送消息→运行→删除（建议使用后删除，避免资源占用） |
| Run（运行） | 触发助手处理线程中消息的“执行指令” | 1. 核心作用：告诉助手“处理当前线程的消息并返回回复” 2. 两种模式： - create_and_poll：同步等待完成（一次性返回结果） - create（stream=True）：流式返回（逐token输出，实时性更好） 3. 状态：queued（排队）→in_progress（处理中）→completed（完成）→failed（失败） |
| 流式返回（Stream） | 助手回复“逐token输出”（而非一次性返回） | 1. 体验：模拟ChatGPT的“打字效果”，实时展示回复过程 2. 优势：减少等待时间，适合实时交互场景 3. 处理方式：需遍历stream对象，逐个解析event事件 |
| Assistant（助手） | 预定义的“智能体”，包含人设、工具、模型 | 1. 核心属性：name（名称）、instructions（人设）、tools（工具）、model（模型） 2. 生命周期：创建→绑定线程→运行→删除（可复用，也可单次使用） |
2. Assistants API核心用法对照表
| 操作 | 函数/方法 | 核心参数 | 作用 |
|---|---|---|---|
| 创建助手 | client.beta.assistants.create() | name、instructions、tools、model | 定义助手的人设、能力、绑定模型 |
| 创建线程 | client.beta.threads.create() | 无（默认参数） | 新建独立的对话会话容器 |
| 发送用户消息 | client.beta.threads.messages.create() | thread_id、role、content | 向指定线程发送用户问题 |
| 触发助手回复（流式） | client.beta.threads.runs.create() | thread_id、assistant_id、stream=True | 流式获取助手的回复（逐token） |
| 触发助手回复（同步） | client.beta.threads.runs.create_and_poll() | thread_id、assistant_id | 等待处理完成后一次性返回结果 |
| 删除线程 | client.beta.threads.delete() | thread_id | 清理线程资源 |
| 删除助手 | client.beta.assistants.delete() | assistant_id | 清理助手资源 |
3. Print函数与流式输出说明（含输出示例）
| 代码行 | 输出示例（核心片段） | 核心作用 |
|---|---|---|
print('=== 流式返回的单个事件（JSON格式） ===') | （分隔符，标识每个流式事件） | 提升输出可读性，区分不同事件 |
print(event.model_dump_json(indent=2, exclude_unset=True)) |
4. 常见问题与解决方案
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 报错“Code Interpreter tool requires gpt-4o/gpt-4-turbo” | 模型指定为gpt-3.5-turbo（不支持Code Interpreter） | 必须将model改为gpt-4o或gpt-4-turbo |
| 流式返回无输出/输出为空 | stream=True但未正确遍历event，或事件状态未到“delta” | 1. 确保遍历stream的循环正确执行 2. 过滤有效事件：仅处理 event.event == 'thread.message.delta'的事件 |
| 报错“API key not found” | 未配置OPENAI_API_KEY环境变量 | 1. 从OpenAI官网获取API密钥 2. 终端执行：Linux/Mac→export OPENAI_API_KEY=“sk-xxx”；Windows→set OPENAI_API_KEY=“sk-xxx” |
| 运行状态一直是“queued” | 网络超时或API调用频率超限 | 1. 检查代理配置是否正确 2. 降低调用频率（OpenAI免费额度有速率限制） |
四、总结
- 核心目标：掌握OpenAI Assistants API（Beta版）的完整使用流程，理解“创建助手→创建线程→发送消息→流式获取回复→清理资源”的核心逻辑，学会使用Code Interpreter工具实现数学计算；
- 关键知识点：
- Assistants API是构建“工具辅助型智能助手”的核心接口，Code Interpreter工具是数学/代码场景的关键；
- Thread（线程）自动维护上下文，Run（运行）触发助手回复，流式返回提升实时交互体验；
- gpt-4o是唯一适配Code Interpreter的主流模型，使用后需删除线程/助手避免资源浪费；
- 实用价值：
- 可扩展为完整的数学辅导助手（支持解方程、微积分、数据计算）；
- 理解“工具调用”是大模型从“纯对话”到“实用工具”的核心能力。