graph_rag_server/docs/api.md

API Documentation

本文档描述了 RAG 系统的所有 REST API 端点。

基础信息

• Base URL: http://localhost:8000
• API Version: v1
• Content Type: application/json
• Authentication: 根据配置可能需要 API Key

通用响应格式

成功响应

{
  "data": { ... },
  "message": "Success"
}

错误响应

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": { ... }
  }
}

健康检查端点

GET /health

检查系统健康状态。

响应:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0"
}

GET /health/ready

检查系统是否准备好接收请求。

响应:

{
  "ready": true,
  "checks": {
    "database": "ok",
    "vector_db": "ok"
  }
}

GET /health/live

检查系统是否存活。

响应:

{
  "alive": true
}

GET /metrics

获取系统性能指标。

响应:

{
  "requests_total": 1000,
  "requests_per_second": 10.5,
  "average_response_time": 0.15,
  "error_rate": 0.01
}

文档管理端点

POST /api/v1/documents/

创建新文档。

请求体:

{
  "content": "Document content",
  "metadata": {
    "title": "Document Title",
    "author": "Author Name",
    "tags": ["tag1", "tag2"]
  },
  "knowledge_base_id": "kb_123"
}

响应:

{
  "id": "doc_456",
  "content": "Document content",
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET /api/v1/documents/{id}

获取文档详情。

路径参数:

• id (string): 文档 ID

响应:

{
  "id": "doc_456",
  "content": "Document content",
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

PUT /api/v1/documents/{id}

更新文档。

路径参数:

• id (string): 文档 ID

请求体:

{
  "content": "Updated content",
  "metadata": {
    "title": "Updated Title"
  }
}

响应:

{
  "id": "doc_456",
  "content": "Updated content",
  "metadata": { ... },
  "updated_at": "2024-01-01T00:00:00Z"
}

DELETE /api/v1/documents/{id}

删除文档。

路径参数:

• id (string): 文档 ID

响应:

{
  "message": "Document deleted successfully"
}

POST /api/v1/documents/search

搜索文档。

请求体:

{
  "query": "search query",
  "filters": {
    "knowledge_base_id": "kb_123",
    "tags": ["tag1"]
  },
  "limit": 10,
  "offset": 0,
  "search_type": "hybrid"
}

搜索类型:

• vector: 仅向量搜索
• text: 仅全文搜索
• hybrid: 混合搜索（默认）

响应:

{
  "results": [
    {
      "id": "doc_456",
      "content": "Document content",
      "score": 0.95,
      "metadata": { ... }
    }
  ],
  "total": 100,
  "limit": 10,
  "offset": 0
}

文档解析端点

POST /api/v1/documents/parse

解析上传的文档（PDF、图片等）。

请求:

• Content-Type: multipart/form-data
• Form fields:
  • file: 文档文件
  • document_type: 文档类型（pdf, image）
  • options: 解析选项（JSON 字符串）

解析选项示例:

{
  "chunking_strategy": "sliding_window",
  "chunk_size": 512,
  "chunk_overlap": 50,
  "extract_images": true
}

响应:

{
  "document_id": "doc_789",
  "chunks": [
    {
      "id": "chunk_1",
      "content": "Chunk content",
      "metadata": {
        "page": 1,
        "position": 0
      }
    }
  ],
  "metadata": {
    "total_pages": 10,
    "total_chunks": 50,
    "file_size": 1024000
  }
}

知识库管理端点

POST /api/v1/knowledge-bases/

创建新知识库。

请求体:

{
  "name": "Knowledge Base Name",
  "description": "Description",
  "metadata": {
    "domain": "technical",
    "language": "zh-CN"
  }
}

响应:

{
  "id": "kb_123",
  "name": "Knowledge Base Name",
  "description": "Description",
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z"
}

GET /api/v1/knowledge-bases/{id}

获取知识库详情。

路径参数:

• id (string): 知识库 ID

响应:

{
  "id": "kb_123",
  "name": "Knowledge Base Name",
  "description": "Description",
  "document_count": 100,
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

PUT /api/v1/knowledge-bases/{id}

更新知识库。

路径参数:

• id (string): 知识库 ID

请求体:

{
  "name": "Updated Name",
  "description": "Updated Description"
}

响应:

{
  "id": "kb_123",
  "name": "Updated Name",
  "description": "Updated Description",
  "updated_at": "2024-01-01T00:00:00Z"
}

DELETE /api/v1/knowledge-bases/{id}

删除知识库。

路径参数:

• id (string): 知识库 ID

查询参数:

• delete_documents (boolean): 是否同时删除关联的文档（默认 false）

响应:

{
  "message": "Knowledge base deleted successfully"
}

POST /api/v1/knowledge-bases/{id}/documents

向知识库添加文档。

路径参数:

• id (string): 知识库 ID

请求体:

{
  "document_ids": ["doc_456", "doc_789"]
}

响应:

{
  "added": 2,
  "failed": 0,
  "knowledge_base_id": "kb_123"
}

DELETE /api/v1/knowledge-bases/{id}/documents/{document_id}

从知识库移除文档。

路径参数:

• id (string): 知识库 ID
• document_id (string): 文档 ID

响应:

{
  "message": "Document removed from knowledge base"
}

GET /api/v1/knowledge-bases/{id}/documents

获取知识库中的文档列表。

路径参数:

• id (string): 知识库 ID

查询参数:

• limit (integer): 每页数量（默认 20）
• offset (integer): 偏移量（默认 0）

响应:

{
  "documents": [
    {
      "id": "doc_456",
      "content": "Document content",
      "metadata": { ... }
    }
  ],
  "total": 100,
  "limit": 20,
  "offset": 0
}

错误代码

错误代码	HTTP 状态码	描述
VALIDATION_ERROR	400	请求参数验证失败
RESOURCE_NOT_FOUND	404	资源不存在
DUPLICATE_RESOURCE	409	资源已存在
INTERNAL_ERROR	500	内部服务器错误
DATABASE_ERROR	500	数据库错误
VECTOR_DB_ERROR	500	向量数据库错误
PARSING_ERROR	422	文档解析失败
INVALID_FILE_TYPE	422	不支持的文件类型

速率限制

• 默认速率限制：100 请求/分钟
• 搜索端点：20 请求/分钟
• 文档解析端点：10 请求/分钟

超过速率限制将返回 429 状态码。

分页

所有列表端点支持分页：

查询参数:

• limit: 每页数量（默认 20，最大 100）
• offset: 偏移量（默认 0）

响应包含:

• total: 总数量
• limit: 当前每页数量
• offset: 当前偏移量

自动生成的 API 文档

FastAPI 自动生成交互式 API 文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

示例代码

Python 客户端示例

import requests

# 创建文档
response = requests.post(
    "http://localhost:8000/api/v1/documents/",
    json={
        "content": "Document content",
        "metadata": {"title": "Test Document"}
    }
)
document = response.json()

# 搜索文档
response = requests.post(
    "http://localhost:8000/api/v1/documents/search",
    json={
        "query": "search query",
        "limit": 10
    }
)
results = response.json()

cURL 示例

# 创建文档
curl -X POST http://localhost:8000/api/v1/documents/ \
  -H "Content-Type: application/json" \
  -d '{"content": "Document content", "metadata": {"title": "Test"}}'

# 搜索文档
curl -X POST http://localhost:8000/api/v1/documents/search \
  -H "Content-Type: application/json" \
  -d '{"query": "search query", "limit": 10}'

# 上传并解析文档
curl -X POST http://localhost:8000/api/v1/documents/parse \
  -F "file=@document.pdf" \
  -F "document_type=pdf"

版本控制

API 使用 URL 路径进行版本控制：/api/v1/...

当前版本：v1

向后兼容性

系统保持向后兼容性，旧的 API 端点仍然可用但会记录废弃警告。建议迁移到新的 API 端点。

支持

如有问题，请参考：

• 架构文档
• 配置指南
• GitHub Issues