06_AI API 接口说明（当前实现版）

本文档基于实际代码实现，反映当前 AI 接口的完整功能状态。当前实现包含：智能分流聊天入口、意图识别、双通道工作流、流式输出等能力。

1. 系统架构概览

1.1 核心特性

智能分流：基于意图识别自动路由到最合适的 AI 模型
双通道工作流：在某些模式下输出 WorkPlan，前端再调用专长接口
多模态支持：文本、图像、视频、代码生成等能力
流式输出：支持 SSE 进行逐行推送
安全与限流：JWT 鉴权、速率限制与超时设置

1.2 工作流程

请求 -> 意图识别 -> 路由决策 -> 调用对应模型 API -> 返回结果
若开启“左侧 Claude 处理”，则左侧输出自然对话，右侧输出 WorkPlan；若未开启，走意图路由到具体能力

2. 环境配置

2.1 必需配置

NEW_API_BASE_URL：new-api 聚合服务地址（默认 https://www.api.moduoduo.cn）
NEW_API_KEY：new-api 访问密钥
AI_INTENT_BASE_URL：意图识别服务地址（默认 https://www.moduoduo.pro）
AI_INTENT_KEY：意图识别 API Key

凭据解析优先级：用户分配 > 学校默认 > 全局（NEW_API_KEY / AI_INTENT_KEY）。对于 NEW_API，若存储为裸 key，后端会在请求前自动补齐 sk- 前缀。

2.2 模型与能力配置

AI_DEFAULT_HUMANITIES_MODEL：人文问答默认模型
AI_STEM_MODEL：理科问答模型
AI_VISION_MODEL：图像理解模型
AI_T2I_MODEL：文生图模型
AI_T2V_MODEL：文生视频模型
AI_CODE_MODEL：代码生成模型
AI_INTENT_MODEL：意图识别模型

2.3 功能开关

AI_LEFT_CHAT_BY_CLAUDE：是否让 Claude 负责左侧聊天
AI_REQUIRE_AUTH：是否开启鉴权
AI_RATE_LIMIT_PER_MINUTE：每分钟限流
AI_REQUEST_TIMEOUT：请求超时（秒）

3. 核心接口

3.1 POST /ai/chat

功能：统一的 AI 聊天入口，自动识别用户意图并路由到最合适的模型。

请求示例：

json

{
  "messages": [
    {"role": "system", "content": "你是一个学习助手"},
    {"role": "user", "content": "请帮我解方程 x^2 - 5x + 6 = 0"}
  ],
  "stream": true
}

行为：

如果 AI_LEFT_CHAT_BY_CLAUDE 为 true，调用 _handle_left_chat_by_claude(payload, request, user)
否则，先通过意图识别 classify_intent(...) 得到 intent，然后按以下路由：
- stem_qa → _handle_stem_qa
- humanities_qa → _handle_humanities_qa
- vision_qa → _handle_vision_qa
- t2i → _handle_text_to_image
- t2v → _handle_text_to_video
- codegen → _handle_code_generation
- 以上未命中时回退到 humanities_qa

流式输出：数据以 SSE 形式逐行传输，最终结束信号为 data: [DONE]

3.2 其他路由（实现细节）

POST /ai/chat/humanities：人文问答，支持双通道输出
POST /ai/chat/stem：理科问答，注入理科助教提示
POST /ai/vision：图像理解，支持多模态输入
POST /ai/draw：文生图，支持多参数，返回结果可保存
POST /ai/video/task：文生视频，异步任务提交
GET /ai/video/task/{task_id}：查询视频任务进度
POST /ai/code：代码生成

3.3 辅助端点

POST /ai/route-plan：仅进行意图识别与路由规划（调试用）
GET /ai/models：返回当前配置的模型信息

4. 意图识别机制

4.1 识别流程

本地启发式快速判断是否为明显的编程请求
调用 Claude 进行深度意图分析
根据识别结果路由到对应能力

4.2 本地规则

编程相关关键词检测（语言、函数、代码标记等）
理科问题关键词（方程、公式、几何等）

4.3 示例

输入示例与预测意图、路由模型对照表（见上文）

5. 双通道协议

5.1 协议说明

若开启双通道：左侧输出自然对话，右侧输出 WorkPlan，前端据此调用专长接口。

5.2 WorkPlan 格式

json

{
  "work": {
    "need": true,
    "type": "essay|stem|image|video|code|vision|none",
    "title": "作品标题",
    "engine": "使用的模型",
    "inputs": {...},
    "ui": {"preview_markdown": "", "auto_execute": true}
  }
}

5.3 工作流程

用户提问
Claude 分析并输出双通道响应
前端解析 WorkPlan
调用对应专长接口
呈现最终结果

6. 安全与限流

JWT 鉴权、限流、超时等机制
内容安全与年龄适配提示词

7. 使用示例

7.1 智能分流聊天

流式聊天（SSE）

bash

curl -N -X POST "http://localhost:8000/ai/chat" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "messages": [
      {"role": "system", "content": "你是一个学习助手"},
      {"role": "user", "content": "请详细解释什么是人工智能"}
    ],
    "stream": true
  }'

Python 流式调用示例

python

import requests
import json

url = "http://localhost:8000/ai/chat"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_JWT_TOKEN"
}
data = {
    "messages": [
        {"role": "user", "content": "请介绍一下深度学习"}
    ],
    "stream": True
}

response = requests.post(url, headers=headers, json=data, stream=True)
for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            data_str = line[6:]
            if data_str == '[DONE]':
                print("\n[完成]")
                break
            try:
                obj = json.loads(data_str)
                content = obj.get('choices', [{}])[0].get('delta', {}).get('content', '')
                if content:
                    print(content, end='', flush=True)
            except json.JSONDecodeError:
                continue

7.2 理科问答

数学问题求解

bash

curl -X POST "http://localhost:8000/ai/chat/stem" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "messages": [
      {"role": "user", "content": "请帮我解方程 x^2 - 5x + 6 = 0，并说明解题步骤"}
    ],
    "stream": false
  }'

物理问题分析

bash

curl -X POST "http://localhost:8000/ai/chat/stem" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "messages": [
      {"role": "user", "content": "一个物体从10米高处自由落体，求落地时的速度"}
    ],
    "stream": true
  }'

7.3 图像理解

图片 URL 分析

bash

curl -X POST "http://localhost:8000/ai/vision" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "prompt": "请详细描述这张图片中的内容，包括人物、物体、场景等",
    "images": [
      {"type": "image_url", "url": "https://example.com/school_scene.jpg"}
    ],
    "stream": false
  }'

Base64 图片分析

bash

curl -X POST "http://localhost:8000/ai/vision" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "prompt": "这是一道数学题的图片，请帮我解答",
    "images": [
      {"type": "image_base64", "data": "iVBORw0KGgoAAAANSUhEUgAA..."}
    ],
    "stream": true
  }'

7.4 文生图

基础图片生成

bash

curl -X POST "http://localhost:8000/ai/draw" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "prompt": "a cute cat astronaut floating in space, digital art style",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }'

教育场景图片生成

bash

curl -X POST "http://localhost:8000/ai/draw" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "prompt": "children studying in a modern classroom with interactive whiteboard, bright and colorful",
    "size": "1792x1024",
    "n": 1,
    "response_format": "b64_json"
  }'

7.5 代码生成

Python 函数生成

bash

curl -X POST "http://localhost:8000/ai/code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "messages": [
      {"role": "user", "content": "用Python写一个计算斐波那契数列的函数，要求支持缓存优化"}
    ],
    "stream": false,
    "language_hint": "python"
  }'

算法实现

bash

curl -X POST "http://localhost:8000/ai/code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "messages": [
      {"role": "user", "content": "实现一个二分查找算法，包含详细注释和测试用例"}
    ],
    "stream": true,
    "language_hint": "python"
  }'

7.6 文生视频

视频任务提交

bash

curl -X POST "http://localhost:8000/ai/video/task" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "content": [
      {"type": "text", "text": "A happy student writing on a blackboard in a classroom"},
      {"type": "image_url", "image_url": {"url": "https://example.com/classroom.jpg"}}
    ]
  }'

查询视频任务状态

bash

curl -X GET "http://localhost:8000/ai/video/task/your_task_id_here" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

7.7 意图路由测试

调试意图识别

bash

curl -X POST "http://localhost:8000/ai/route-plan" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "messages": [
      {"role": "user", "content": "写一个Python爬虫程序"}
    ]
  }'

返回示例

json

{
  "intent": "codegen",
  "reason": "用户请求编写Python程序，属于代码生成需求",
  "model": "qwen3-coder-plus",
  "messages": [
    {"role": "user", "content": "写一个Python爬虫程序"}
  ]
}

7.8 模型信息查询

bash

curl -X GET "http://localhost:8000/ai/models" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

返回示例

json

{
  "models": {
    "humanities": "ernie-4.5-turbo-vl",
    "stem": "qwen3-235b-a22b-thinking-2507",
    "vision": "ernie-4.5-turbo-vl",
    "t2i": "Doubao-seedream-3-0-t2i",
    "t2v": "Doubao-seedance-1-0-pro",
    "code": "qwen3-coder-plus"
  },
  "configured": true
}

06_AI API 接口说明（当前实现版） ​

1. 系统架构概览 ​

1.1 核心特性 ​

1.2 工作流程 ​

2. 环境配置 ​

2.1 必需配置 ​

2.2 模型与能力配置 ​

2.3 功能开关 ​

3. 核心接口 ​

3.1 POST /ai/chat ​

3.2 其他路由（实现细节） ​

3.3 辅助端点 ​

4. 意图识别机制 ​

4.1 识别流程 ​

4.2 本地规则 ​

4.3 示例 ​

5. 双通道协议 ​

5.1 协议说明 ​

5.2 WorkPlan 格式 ​

5.3 工作流程 ​

6. 安全与限流 ​

7. 使用示例 ​

7.1 智能分流聊天 ​

7.2 理科问答 ​

7.3 图像理解 ​

7.4 文生图 ​

7.5 代码生成 ​

7.6 文生视频 ​

7.7 意图路由测试 ​

7.8 模型信息查询 ​

06_AI API 接口说明（当前实现版）

1. 系统架构概览

1.1 核心特性

1.2 工作流程

2. 环境配置

2.1 必需配置

2.2 模型与能力配置

2.3 功能开关

3. 核心接口

3.1 POST /ai/chat

3.2 其他路由（实现细节）

3.3 辅助端点

4. 意图识别机制

4.1 识别流程

4.2 本地规则

4.3 示例

5. 双通道协议

5.1 协议说明

5.2 WorkPlan 格式

5.3 工作流程

6. 安全与限流

7. 使用示例

7.1 智能分流聊天

7.2 理科问答

7.3 图像理解

7.4 文生图

7.5 代码生成

7.6 文生视频

7.7 意图路由测试

7.8 模型信息查询