当前位置：首页 > news >正文

LLM大模型 - 实战篇 - Assistant API 原理与实战应用

news 2025/9/20 7:15:29

一、Assistant API概述

1.1 什么是Assistant API？

OpenAI在2023年11月6日的开发者大会上推出了Assistants API，这是一个革命性的开发者工具，允许开发者在自己的应用程序中构建功能强大的人工智能助手。这些助手能够根据预设指令运作，并综合利用多种资源来响应用户查询。

1.2 核心功能特性

Assistant API支持三种强大的工具类型：

代码解释器（Code Interpreter）：在沙盒环境中执行Python代码，支持数据分析和文件处理
检索功能（Retrieval）：集成知识库系统，允许助手访问外部文档和信息源
函数调用（Function Calling）：让助手能够调用开发者定义的函数，极大扩展了应用场景

二、Assistant API与GPTs的深度对比

为了更清晰地理解Assistant API的定位，我们将其与GPTs进行详细对比：

特性	GPTs	Assistant API
目标用户	普通用户、业务人员	开发者、技术人员
创建方式	无代码可视化界面	编程接口（需编写代码）
定制程度	中等，受界面限制	极高，可深度定制
部署环境	ChatGPT平台	自有应用程序
数据控制	OpenAI托管	开发者自主控制
分享方式	内置分享机制	需自行实现分享功能
适用场景	通用助手、简单应用	企业级应用、专业领域

三、Assistant API核心原理解析

3.1 核心对象模型

Assistant API建立在五个核心对象之上，构成了完整的工作流程：

3.2 各对象详细功能

3.2.1 Assistant（助手）

特定目的的AI代理
配置包括模型选择、指令设置和工具启用
示例：水果店财务助手、技术支持助手等

3.2.2 Thread（线程）

代表一次对话会话
自动管理上下文长度，处理内容截断
存储所有消息历史

3.2.3 Message（消息）

包含用户和助手之间的通信内容
支持文本、图像和文件等多种格式
按时间顺序存储在Thread中

3.2.4 Run（运行）

触发助手处理Thread中的消息
激活配置的工具（代码解释器、检索等）
生成新的消息并添加到Thread

3.2.5 Run Step（运行步骤）

详细记录助手在Run中的执行过程
可用于调试和优化助手行为
展示工具调用和消息生成的具体步骤

3.3 完整工作流程

创建助手：定义助手的行为特性和可用工具
创建线程：为用户会话建立上下文环境
添加消息：将用户查询加入对话线程
运行助手：激活助手处理线程中的消息
获取响应：检索助手生成的消息和操作结果

四、实战项目：构建水果店财务助手

4.1 项目背景与目标

本项目旨在使用MiniMax平台的Assistant API（因OpenAI API在国内访问限制而选择的替代方案）开发一个专门用于水果销售财务计算的人工智能助手。该助手能够根据销售记录自动计算总成本、总收入和利润。

4.2 数据准备

建立知识库文件fruit_price.txt，包含水果的价格信息：

text

香蕉成本价2元一斤，售价为3元一斤。
橘子成本价1.5元一斤，售价为2.5元一斤。
苹果成本价3元一斤，售价为3.5元一斤。
芒果成本价5元一斤，售价为6元一斤。
葡萄成本价2元一斤，售价为4元一斤。

4.3 环境配置

python

# 导入必要库
import requests  # 发送HTTP请求
import json      # 处理JSON数据
import time      # 处理时间操作
import os        # 操作系统接口
from dotenv import load_dotenv, find_dotenv  # 环境变量管理# 加载环境变量
load_dotenv(find_dotenv())
GroupId = os.environ['GroupId']  # MiniMax的GroupId
API_KEY = os.environ['API_KEY']  # MiniMax的API密钥# 设置请求头
headers = {'Authorization': f'Bearer {API_KEY}',  # 身份验证'Content-Type': 'application/json'     # 数据格式标识
}headers_retrieval = {'Authorization': f'Bearer {API_KEY}','authority': 'api.minimax.chat',       # API服务地址
}

4.4 完整实现代码

4.4.1 文件上传功能

python

def create_file():"""上传知识库文件到MiniMax平台返回：API响应结果，包含文件ID"""url = f"https://api.minimax.chat/v1/files/upload?GroupId={GroupId}"data = {'purpose': 'assistants'}  # 指定文件用途files = {'file': open('fruit_price.txt', 'rb')}  # 打开文件# 发送POST请求上传文件response = requests.post(url, headers=headers_retrieval, data=data, files=files)return response.json()  # 返回JSON格式的响应

4.4.2 创建助手

python

def create_assistant(file_id):"""创建财务助手实例file_id: 上传文件后获取的文件标识返回：API响应结果，包含助手ID"""url = f"https://api.minimax.chat/v1/assistants/create?GroupId={GroupId}"# 构建助手配置payload = json.dumps({"model": "abab5.5-chat",           # 使用的模型版本"name": "水果店财务助手",           # 助手名称"description": "水果店财务助手，用在水果销售过程中计算营业额",  # 助手描述"instructions": "你是一个专业的水果店财务助手，根据每类水果的售出量以及单价，统计其成本和收入，计算出总利润。请提供清晰的计算过程和详细的结果展示。",  # 助手指令"file_ids": [str(file_id)],        # 关联的知识库文件"tools": [{'type': 'retrieval'}]   # 启用检索功能})response = requests.post(url, headers=headers, data=payload)return response.json()

4.4.3 线程管理

python

def create_thread():"""创建新的对话线程返回：API响应结果，包含线程ID"""url = f"https://api.minimax.chat/v1/threads/create?GroupId={GroupId}"response = requests.post(url, headers=headers)return response.json()def add_message_to_thread(thread_id):"""向指定线程添加用户消息thread_id: 目标线程的标识符返回：API响应结果"""url = f"https://api.minimax.chat/v1/threads/messages/add?GroupId={GroupId}"# 构建消息内容payload = json.dumps({"thread_id": thread_id,"role": "user",  # 发送者角色为用户"content": "我卖了2斤葡萄，3斤半的香蕉，2斤苹果，计算下总成本和总收入，给出具体的计算过程"})response = requests.post(url, headers=headers, data=payload)return response.json()

4.4.4 运行助手与状态检查

python

def run_thread_with_assistant(thread_id, assistant_id):"""在指定线程上运行助手thread_id: 线程标识符assistant_id: 助手标识符返回：API响应结果，包含运行ID"""time.sleep(10)  # 等待助手初始化完成url = f"https://api.minimax.chat/v1/threads/run/create?GroupId={GroupId}"payload = json.dumps({"thread_id": thread_id,"assistant_id": assistant_id})response = requests.post(url, headers=headers, data=payload)return response.json()def check_thread_run_status(thread_id, run_id):"""检查助手运行状态thread_id: 线程标识符run_id: 运行标识符返回：运行是否完成"""url = f"https://api.minimax.chat/v1/threads/run/retrieve?GroupId={GroupId}"payload = json.dumps({"thread_id": str(thread_id),"run_id": str(run_id)})completed = Falsewhile not completed:response = requests.request("GET", url, headers=headers, data=payload)if response.status_code == 200:response_data = response.json()status = response_data.get('status', '')print(f"Status: {status}")if status == "completed":completed = Trueprint("处理完成，退出循环")else:time.sleep(2)  # 等待2秒后重新检查else:print(f"错误: {response.status_code}")break  # 请求失败，退出循环return completed

4.4.5 获取处理结果

python

def get_thread_message(thread_id):"""获取线程中的消息列表thread_id: 线程标识符返回：消息列表的API响应"""url = f"https://api.minimax.chat/v1/threads/messages/list?GroupId={GroupId}"payload = json.dumps({"thread_id": thread_id})response = requests.get(url, headers=headers, data=payload)return response.json()

4.4.6 主程序流程

python

def main():"""主函数，协调整个助手流程"""# 上传知识库文档file_response = create_file()file_id = file_response.get('file', {}).get('file_id')# 创建助手实例assistant_response = create_assistant(file_id)assistant_id = assistant_response.get('id', '')# 创建对话线程thread_response = create_thread()thread_id = thread_response.get('id', '')# 向线程添加用户消息add_message_to_thread(thread_id)# 运行助手处理消息run_response = run_thread_with_assistant(thread_id, assistant_id)run_id = run_response.get('id', '')# 检查处理状态if check_thread_run_status(thread_id, run_id):# 获取并展示处理结果thread_message_response = get_thread_message(thread_id)print(json.dumps(thread_message_response, indent=4, ensure_ascii=False))if __name__ == "__main__":main()

4.5 执行结果分析

当程序成功运行后，助手会返回类似以下的计算结果：

json

{"value": "根据上述信息，可以计算出总成本和总收入。\n\n首先，我们需要知道各类水果的成本和售价，根据查询结果，我们可以知道：\n- 葡萄的成本价为2元/斤，售价为4元/斤；\n- 香蕉的成本价为2元/斤，售价为3元/斤；\n- 苹果的成本价为3元/斤，售价为3.5元/斤。\n\n然后，我们可以计算总成本和总收入：\n- 2斤葡萄的总成本 = 2斤 * 2元/斤 = 4元；\n- 3斤半的香蕉的总成本 = 3.5斤 * 2元/斤 = 7元；\n- 2斤苹果的总成本 = 2斤 * 3元/斤 = 6元。\n\n总成本 = 4元 + 7元 + 6元 = 17元。\n\n- 2斤葡萄的总收入 = 2斤 * 4元/斤 = 8元；\n- 3斤半的香蕉的总收入 = 3.5斤 * 3元/斤 = 10.5元；\n- 2斤苹果的总收入 = 2斤 * 3.5元/斤 = 7元。\n\n总收入 = 8元 + 10.5元 + 7元 = 25.5元。\n\n最后，我们可以计算出总利润：\n总利润 = 总收入 - 总成本 = 25.5元 - 17元 = 8.5元。\n\n所以，你总共赚了8.5元。"
}