#知识库 API

管理知识库、文档和向量检索。知识库用于为 Agent 提供领域知识上下文（RAG）。

基础路径: /v1/knowledge-bases

#知识库管理

#列出知识库

CopyGET /v1/knowledge-bases

所需权限: read

#查询参数

#响应

jsonCopy{
  "data": [
    {
      "id": "kb_abc123",
      "name": "产品文档库",
      "description": "产品相关文档",
      "documentCount": 15,
      "embeddingModel": "text-embedding-ada-002",
      "organizationId": "org_xxx",
      "projectId": "proj_xxx",
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-15T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

#获取知识库详情

CopyGET /v1/knowledge-bases/:kbId

所需权限: read

#创建知识库

CopyPOST /v1/knowledge-bases

所需权限: write

#请求体

jsonCopy{
  "name": "产品文档库",
  "description": "存储所有产品相关文档",
  "embeddingModel": "text-embedding-ada-002",
  "embeddingProvider": "openai",
  "apiKeyConfigId": "config_xxx",
  "chunkSize": 500,
  "chunkOverlap": 50
}

#响应

CopyHTTP 201 Created

#更新知识库

CopyPATCH /v1/knowledge-bases/:kbId

所需权限: write

#请求体

jsonCopy{
  "name": "更新后的名称",
  "description": "更新后的描述",
  "settings": {}
}

#删除知识库

CopyDELETE /v1/knowledge-bases/:kbId

所需权限: admin

#响应

jsonCopy{
  "id": "kb_abc123",
  "deleted": true
}

#文档管理

#列出文档

CopyGET /v1/knowledge-bases/:kbId/documents

所需权限: read

#响应

jsonCopy{
  "data": [
    {
      "id": "doc_xxx",
      "name": "用户手册.pdf",
      "status": "processed",
      "chunkCount": 42,
      "size": 1048576,
      "createdAt": "2026-02-01T08:00:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

#获取文档详情

CopyGET /v1/knowledge-bases/:kbId/documents/:docId

所需权限: read

#上传文档

CopyPOST /v1/knowledge-bases/:kbId/documents

所需权限: write

使用 multipart/form-data 格式上传文件：

bashCopycurl -X POST "https://your-domain.com/v1/knowledge-bases/kb_abc123/documents" \
  -H "X-API-Key: sk_your_api_key_here" \
  -F "file=@./document.pdf"

#批量上传（URL）

CopyPOST /v1/knowledge-bases/:kbId/documents/batch

所需权限: write

#请求体

jsonCopy{
  "urls": [
    "https://example.com/doc1.pdf",
    "https://example.com/doc2.md"
  ],
  "tags": ["product", "v2"]
}

#响应

CopyHTTP 202 Accepted

jsonCopy{
  "data": [
    {
      "url": "https://example.com/doc1.pdf",
      "status": "queued",
      "documentId": "doc_xxx"
    }
  ],
  "meta": {
    "total": 1,
    "jobId": "job_xxx"
  }
}

#删除文档

CopyDELETE /v1/knowledge-bases/:kbId/documents/:docId

所需权限: admin

#响应

jsonCopy{
  "id": "doc_xxx",
  "deleted": true
}

#导入任务

批量导入时会创建导入任务，用于跟踪处理进度。

#创建导入任务

CopyPOST /v1/knowledge-bases/:kbId/import-jobs

所需权限: write

使用 multipart/form-data 格式，支持文件上传和 URL 源：

#响应

CopyHTTP 202 Accepted

#列出导入任务

CopyGET /v1/knowledge-bases/:kbId/import-jobs

所需权限: read

#查询参数

#获取导入任务详情

CopyGET /v1/knowledge-bases/:kbId/import-jobs/:jobId

所需权限: read

返回任务详情及关联的文档处理进度。

#取消导入任务

CopyDELETE /v1/knowledge-bases/:kbId/import-jobs/:jobId

所需权限: admin

#响应

jsonCopy{
  "id": "job_xxx",
  "status": "cancelled",
  "cancelledDocuments": 3,
  "alreadyProcessed": 2
}

#重试失败文档

CopyPOST /v1/knowledge-bases/:kbId/import-jobs/:jobId/retry

所需权限: write

#响应

jsonCopy{
  "id": "job_xxx",
  "status": "processing",
  "retriedDocuments": 2
}

#搜索

#搜索知识库

CopyPOST /v1/knowledge-bases/:kbId/search

所需权限: write

#请求体

jsonCopy{
  "query": "如何配置系统参数",
  "topK": 5,
  "scoreThreshold": 0.7,
  "filters": {}
}

#响应

jsonCopy{
  "query": "如何配置系统参数",
  "results": [
    {
      "documentId": "doc_xxx",
      "documentName": "系统配置指南",
      "content": "系统参数可以通过以下方式配置...",
      "score": 0.95,
      "metadata": {}
    }
  ],
  "totalResults": 1,
  "searchTime": 0.125
}