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 接入等扩展功能，增强助手的实用性与智能度。