obsidian-valut-mq/美洽AI/Rag/RAG对外接口文档.md

本文档对应以下 3 个内部接口：

• POST /rag/index
• POST /rag/query
• POST /rag/delete

baseURL: http://api-gateway.meiqia.cn/openapi/

请求头使用：

Content-Type: application/json
OrgName: {org_name}
Token: {token}

org_name和token一一对应 org_name枚举：meiqia、laigu token等开发之后会提供

通用响应格式

接口成功时：

{
  "success": true,
  "data": {}
}

说明：

• 成功时 HTTP 状态码通常为 200
• 如果接口返回为空，响应可能只有 {"success": true}

接口失败时：

{
  "success": false,
  "message": "missing required fields"
}

说明：

• 参数错误默认返回 400
• 部分服务内部错误可能返回 500

1. 索引文档

接口地址

POST /rag/index

接口说明

将指定知识库文档下载后切分为 RAG chunk，并写入 RAG 检索集合。

补充说明：

• file_url 为服务端可访问的文件下载地址
• 文件类型主要根据 file_name 后缀或 file_url 路径后缀识别
• 当前代码中明确支持的文件类型有：.md、.pdf、.txt、.docx、.xlsx、.xls、.csv

请求参数

字段	类型	必填	说明
ent_id	int64	是	企业 ID
knowledge_id	string	是	知识库 ID
knowledge_doc_id	string	是	知识文档 ID
file_name	string	否	文件名，建议传真实文件名及后缀，便于识别文件类型
file_url	string	是	文件下载地址

请求示例

{
  "ent_id": 10001,
  "knowledge_id": "kb_001",
  "knowledge_doc_id": "doc_001",
  "file_name": "产品使用手册.pdf",
  "file_url": "https://example.com/files/doc_001.pdf"
}

成功响应示例

{
  "success": true
}

失败响应示例

{
  "success": false,
  "message": "unsupported file type: .zip"
}

2. 查询 RAG 文本

接口地址

POST 
/rag/query

接口说明

根据问题和知识库 ID 列表检索最相关的 RAG 文本片段。

补充说明：

• knowledge_ids 至少需要传 1 个
• 当 top_k <= 0 时，服务端会自动使用默认值 10
• 当前接口只返回文本内容，不返回分数、文档 ID、chunk 索引等元数据

请求参数

字段	类型	必填	说明
ent_id	int64	是	企业 ID
knowledge_ids	[]string	是	待检索的知识库 ID 列表
query	string	是	用户查询问题
top_k	int	否	返回条数，未传或小于等于 0 时默认取 10

请求示例

{
  "ent_id": 10001,
  "knowledge_ids": ["kb_001", "kb_002"],
  "query": "如何重置管理员密码？",
  "top_k": 5
}

成功响应示例

{
  "success": true,
  "data": {
    "texts": [
      "管理员可以在设置中心的账号安全页面重置密码。",
      "如果开启了双重验证，重置密码后需要重新绑定验证设备。"
    ]
  }
}

失败响应示例

{
  "success": false,
  "message": "missing required fields"
}

3. 删除文档索引

接口地址

POST /rag/delete

接口说明

删除指定知识文档的索引数据。

实际行为如下：

• 删除指定知识文档的 RAG 索引数据
• knowledge_id 不是必填
• 当 knowledge_id 为空时，会按 ent_id + knowledge_doc_id 删除
• 当 knowledge_id 不为空时，会按 ent_id + knowledge_id + knowledge_doc_id 精确删除

请求参数

字段	类型	必填	说明
ent_id	int64	是	企业 ID
knowledge_id	string	否	知识库 ID；传入后删除范围更精确
knowledge_doc_id	string	是	知识文档 ID

请求示例

{
  "ent_id": 10001,
  "knowledge_id": "kb_001",
  "knowledge_doc_id": "doc_001"
}

成功响应示例

{
  "success": true
}

失败响应示例

{
  "success": false,
  "message": "missing required fields"
}