Assistant API的原理及应用

---

什么是 Assistants API？

**发布日期：**2023年11月6日，OpenAI在开发者大会上发布了 Assistants API —— 一款面向开发者的工具，用于在应用中构建 AI 助手。

✅ 它可以做什么？

Assistants API 允许开发者构建智能助手，这些助手可通过：

• instructions（指令）：设定助手行为；
• models（模型）：指定使用的 GPT 模型；
• tools（工具）：调用代码解释器、知识库检索等功能；
• knowledge（知识）：接入外部知识库提升回答能力。

---

当前支持的工具类型：

工具名	中文含义	功能简介
Code Interpreter	代码解释器	运行代码、执行计算任务
Retrieval	检索	与知识库集成，支持 RAG
Function Calling	函数调用	调用自定义 API 或业务逻辑

---

Assistants API vs GPTs 的区别与联系

对比维度	Assistants API	GPTs
创建方式	编写代码集成	无代码配置（ChatGPT界面）
部署位置	集成进自定义产品中	使用 ChatGPT Web
UI 体验	需开发者自定义 UI	ChatGPT 原生 UI
分享功能	无内置	内置分享 GPTs

共同点：

• 都基于 OpenAI 的 GPT 技术；
• 都支持指令、知识库等定制化；
• 都用于提供个性化智能助手体验。

---

⚙️ Assistant API 的原理与核心流程

Assistants API 核心概念图解：

概念名	含义说明
Assistant	定义好的 AI 助手，绑定模型、指令、工具等
Thread	用户与助手的对话历史上下文
Message	单条对话信息，可以是文字、图片等
Run	发起一次助手任务执行
Run Step	助手执行任务的详细过程（是否调用工具等）

整体执行流程如下：

1. 创建 Assistant：设置指令、选择模型，绑定工具和文件；
2. 创建 Thread：创建对话线程；
3. 添加 Message：将用户问题添加进线程；
4. 执行 Run：触发一次对话逻辑，模型生成回答；
5. 读取结果：助手将在 Thread 中附加响应。

⚠️ 当前为 beta 阶段，部分功能可能不稳定或在持续迭代中。

---

️ 实践项目：构建一个“水果收银助手”

✨ 项目背景

使用 MiniMax 开放平台 模拟 OpenAI Assistants API，实现一个能帮我们计算水果利润的助手。

文件准备：我们先创建 fruit_price.txt，内容如下：

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

---

✅ 实现流程详解

---

3.1 导入工具包

import requests    # 用于发送 HTTP 请求
import json        # JSON 数据处理
import time, os
from dotenv import load_dotenv, find_dotenv  # 读取 .env 文件中的环境变量

---

⚙️ 3.2 配置环境变量

_ = load_dotenv(find_dotenv())
GroupId = os.environ['GroupId']
API_KEY = os.environ['API_KEY']

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

headers_retrieval = {
    'Authorization': f'Bearer {API_KEY}',
    'authority': 'api.minimax.chat',
}

---

3.3 上传文件

def create_file():
    url = f"https://api.minimax.chat/v1/files/upload?GroupId={GroupId}"
    files = {'file': open('./fruit_price.txt', 'rb')}
    data = {'purpose': 'assistants'}
    response = requests.post(url, headers=headers_retrieval, data=data, files=files)
    return response.json()

---

3.4 创建助手（Assistant）

def create_assistant(file_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()

常用模型版本：abab5.5-chat, abab6.5-chat, abab6.5s-chat, 支持多种工具组合。

---

3.5 创建线程

def create_thread():
    url = f"https://api.minimax.chat/v1/threads/create?GroupId={GroupId}"
    response = requests.post(url, headers=headers)
    return response.json()

---

3.6 添加消息到线程

def add_message_to_thread(thread_id):
    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()

---

▶️ 3.7 运行助手

def run_thread_with_assistant(thread_id, assistant_id):
    time.sleep(200)  # 等待 Assistant 向量化文件完成
    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()

---

3.8 查看运行状态

def check_thread_run_status(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 = False
    while not completed:
        response = requests.request("GET", url, headers=headers, data=payload)
        if response.status_code == 200:
            status = response.json().get('status', '')
            print(f"Status: {status}")
            if status == 'completed':
                completed = True
            else:
                time.sleep(2)
        else:
            print(f"Error: {response.status_code}")
            break
    return completed

---

3.9 获取助手回复

def get_thread_messages(thread_id):
    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()

---

✅ 总结

通过 MiniMax 平台模拟使用 OpenAI 的 Assistants API，可以体验构建专属 AI 助手的流程，特别适合教学、企业内训与原型系统开发。下一步可以加入函数调用、外部 API 接入等扩展功能，增强助手的实用性与智能度。