Skip to content

Latest commit

 

History

History
263 lines (202 loc) · 5.97 KB

API.md

File metadata and controls

263 lines (202 loc) · 5.97 KB

API 文档

Course Materials RAG System 的完整API文档，包含顺序工具调用功能。

基础信息

  • Base URL: http://localhost:8000
  • 版本: v1.0 (支持顺序工具调用)
  • 认证: 无需认证（本地开发环境）
  • 内容类型: application/json

核心端点

1. 主查询端点 (支持顺序工具调用)

POST /api/query

最重要的端点，支持复杂查询的多轮工具调用。

请求体

{
  "query": "string",           // 必需：用户查询内容
  "session_id": "string"       // 可选：会话ID用于上下文保持
}

示例请求

# 简单查询 (单工具调用)
curl -X POST http://localhost:8000/api/query \
-H "Content-Type: application/json" \
-d '{
  "query": "What is the MCP course outline?"
}'

# 复杂查询 (可能触发双工具调用)
curl -X POST http://localhost:8000/api/query \
-H "Content-Type: application/json" \
-d '{
  "query": "Give me the MCP course outline, then explain what lesson 3 covers",
  "session_id": "user_123"
}'

响应格式

{
  "answer": "string",          // AI生成的完整回答
  "sources": [                 // 来源信息数组
    {
      "text": "string",        // 来源描述
      "url": "string"          // 可选：相关链接
    }
  ],
  "session_id": "string",      // 会话ID
  "processing_info": {         // 可选：处理信息
    "tool_calls_count": 1,     // 实际使用的工具调用次数
    "processing_time": 4.2     // 处理时间（秒）
  }
}

响应示例

单工具调用响应：

{
  "answer": "The MCP course includes 11 lessons:\n\nLesson 0: Introduction\nLesson 1: Why MCP\n...",
  "sources": [
    {
      "text": "MCP: Build Rich-Context AI Apps with Anthropic - Course Outline",
      "url": "https://www.deeplearning.ai/short-courses/mcp-build-rich-context-ai-apps-with-anthropic/"
    }
  ],
  "session_id": "session_1"
}

双工具调用响应：

{
  "answer": "The MCP course has 11 lessons covering Model Context Protocol development...\n\nLesson 3 specifically focuses on building a practical chatbot example...",
  "sources": [
    {
      "text": "MCP: Build Rich-Context AI Apps with Anthropic - Course Outline",
      "url": "https://www.deeplearning.ai/short-courses/mcp-build-rich-context-ai-apps-with-anthropic/"
    },
    {
      "text": "MCP: Build Rich-Context AI Apps with Anthropic - Lesson 3",
      "url": "https://learn.deeplearning.ai/courses/mcp-build-rich-context-ai-apps-with-anthropic/lesson/hg6oi/chatbot-example"
    }
  ],
  "session_id": "session_2"
}

2. 课程统计端点

GET /api/courses

获取系统中所有课程的统计信息。

响应格式

{
  "total_courses": 4,
  "course_titles": [
    "Building Towards Computer Use with Anthropic",
    "MCP: Build Rich-Context AI Apps with Anthropic",
    "Advanced Retrieval for AI with Chroma",
    "Prompt Compression and Query Optimization"
  ]
}

示例请求

curl http://localhost:8000/api/courses

查询类型和工具调用模式

单工具调用查询

这些查询通常只需要一个工具调用：

课程大纲查询：

  • "What is the MCP course outline?"
  • "How many lessons are in the Advanced Retrieval course?"
  • "Show me all lessons in the Computer Vision course"

内容搜索查询：

  • "What does lesson 3 of MCP course teach?"
  • "Find information about neural networks"
  • "What is covered in the introduction lesson?"

双工具调用查询

这些复杂查询可能触发两次工具调用：

结构 + 内容查询：

  • "Give me the MCP course outline, then explain lesson 3"
  • "How many lessons does MCP have, and what does the first lesson cover?"

比较分析查询：

  • "Compare MCP course structure with Advanced Retrieval course"
  • "What are the differences between course A and course B?"

多维度查询：

  • "Find courses about AI, then show me their lesson structures"
  • "What programming concepts are taught, and in which courses?"

性能特征

响应时间

查询类型 预期响应时间 工具调用次数
通用知识 1-3秒 0
简单搜索 2-6秒 1
复杂分析 6-15秒 1-2

超时保护

  • 单轮超时: 3秒
  • 总处理超时: 10秒
  • 超时时的降级: 返回可用的部分结果

限制

  • 最大工具调用次数: 2次
  • 会话超时: 10秒
  • 查询长度: 建议 < 500字符

错误响应

通用错误格式

{
  "error": "string",           // 错误类型
  "message": "string",         // 详细错误信息
  "code": 400                  // HTTP状态码
}

常见错误

400 Bad Request：

{
  "error": "Invalid query",
  "message": "Query parameter is required and cannot be empty",
  "code": 400
}

500 Internal Server Error：

{
  "error": "Processing error",
  "message": "Tool execution failed after 2 attempts",
  "code": 500
}

408 Request Timeout：

{
  "error": "Timeout",
  "message": "Query processing exceeded 10 second limit",
  "code": 408
}

交互式API文档

系统提供两种交互式API文档：

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

这些界面允许你直接测试API端点并查看实时响应。

WebSocket 支持 (计划中)

未来版本将支持WebSocket连接以提供实时响应流：

// 计划中的WebSocket API
const ws = new WebSocket('ws://localhost:8000/ws');
ws.send(JSON.stringify({
  type: 'query',
  data: { query: 'Your question here' }
}));

SDK 和客户端库 (计划中)

计划为主要编程语言提供SDK：

  • Python SDK
  • JavaScript/Node.js SDK
  • cURL 脚本集合

版本历史

v1.0 (当前)

  • ✅ 顺序工具调用支持
  • ✅ 双工具架构 (outline + content)
  • ✅ 智能超时保护
  • ✅ 多源引用支持

v0.9 (之前)

  • ✅ 基础RAG功能
  • ✅ 单工具调用
  • ✅ 基础会话管理