知识库查询

知识库查询接口允许外部系统通过 OpenAPI 访问 Snail AI 的 RAG 知识库，包括语义搜索和智能问答两种能力。

知识库搜索

基于语义向量和全文检索，从指定知识库中搜索最相关的文档片段。

POST /snail-ai/open-api/rag/search

请求体

字段	类型	必填	说明
`ragId`	`number`	是	知识库 ID
`query`	`string`	是	搜索查询
`debug`	`boolean`	否	是否返回检索性能指标

curl 示例

bash

curl -X POST 'http://localhost:8080/snail-ai/open-api/rag/search' \
  -H 'Content-Type: application/json' \
  -H 'Snail-Ai-Auth: eyJhbGciOiJIUzI1NiJ9...' \
  -d '{
    "ragId": 1,
    "query": "退款政策的具体流程是什么？",
    "debug": false
  }'

响应示例

json

{
  "code": 1,
  "msg": "success",
  "data": {
    "results": [
      {
        "chunkId": 105,
        "content": "退款流程说明：\n1. 用户在订单详情页点击"申请退款"按钮\n2. 填写退款原因和详细说明\n3. 提交申请后，客服团队将在 1-2 个工作日内审核\n4. 审核通过后，退款将在 3-5 个工作日内原路返回",
        "score": 0.94,
        "documentId": 10,
        "documentName": "退款政策.md",
        "metadata": {}
      },
      {
        "chunkId": 108,
        "content": "特殊退款情况：\n- 虚拟商品不支持退款\n- 超过 30 天的订单需联系客服人工处理\n- 活动折扣商品按实付金额退款",
        "score": 0.87,
        "documentId": 10,
        "documentName": "退款政策.md",
        "metadata": {}
      },
      {
        "chunkId": 112,
        "content": "退款到账时间：\n- 支付宝：1-2 个工作日\n- 微信支付：1-3 个工作日\n- 银行卡：3-7 个工作日",
        "score": 0.81,
        "documentId": 11,
        "documentName": "支付说明.md",
        "metadata": {}
      }
    ],
    "metrics": {
      "embeddingMs": 85,
      "vectorSearchMs": 32,
      "bm25SearchMs": 18,
      "fusionMs": 3,
      "rerankMs": 150,
      "totalMs": 288,
      "vectorHitCount": 10,
      "bm25HitCount": 8,
      "finalCount": 3
    }
  }
}

搜索结果字段

字段	类型	说明
`chunkId`	`number`	文档片段 ID
`content`	`string`	片段文本内容
`score`	`number`	相关性评分（0-1）
`documentId`	`number`	所属文档 ID
`documentName`	`string`	所属文档名称
`metadata`	`object`	元数据

性能指标字段（debug=true 时返回）

字段	类型	说明
`embeddingMs`	`number`	向量编码耗时（ms）
`vectorSearchMs`	`number`	向量搜索耗时（ms）
`bm25SearchMs`	`number`	BM25 搜索耗时（ms）
`fusionMs`	`number`	融合排序耗时（ms）
`rerankMs`	`number`	Rerank 耗时（ms）
`totalMs`	`number`	总耗时（ms）
`vectorHitCount`	`number`	向量搜索命中数
`bm25HitCount`	`number`	BM25 搜索命中数
`finalCount`	`number`	最终返回结果数

知识库问答（流式）

基于 RAG 检索增强生成，针对知识库内容进行智能问答，返回流式文本。

POST /snail-ai/open-api/rag/qa/stream

请求体

字段	类型	必填	说明
`ragId`	`number`	是	知识库 ID
`query`	`string`	是	用户问题
`conversationId`	`string`	否	对话 ID（多轮问答时传入）

curl 示例

bash

curl -X POST 'http://localhost:8080/snail-ai/open-api/rag/qa/stream' \
  -H 'Content-Type: application/json' \
  -H 'Snail-Ai-Auth: eyJhbGciOiJIUzI1NiJ9...' \
  -d '{
    "ragId": 1,
    "query": "退款流程是怎样的？需要多长时间？"
  }' \
  --no-buffer

响应格式

返回纯文本流，内容逐块推送。客户端需持续读取流并拼接显示。

流式输出示例：

根据知识库中的退款政策文档，退款流程如下：

## 退款步骤

1. **提交申请**：在订单详情页点击"申请退款"按钮
2. **填写原因**：填写退款原因和详细说明
3. **等待审核**：客服团队将在 1-2 个工作日内完成审核
4. **退款到账**：审核通过后，退款将原路返回

## 到账时间

不同支付方式的到账时间有所不同：
- 支付宝：1-2 个工作日
- 微信支付：1-3 个工作日
- 银行卡：3-7 个工作日

> 注意：虚拟商品不支持退款，超过 30 天的订单需联系客服人工处理。

客户端处理示例

JavaScript：

javascript

async function ragQA(ragId, query, conversationId) {
  const response = await fetch('http://localhost:8080/snail-ai/open-api/rag/qa/stream', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Snail-Ai-Auth': 'your-token'
    },
    body: JSON.stringify({ ragId, query, conversationId })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let fullText = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value, { stream: true });
    fullText += chunk;
    // 实时更新 UI
    updateUI(fullText);
  }

  return fullText;
}

Python：

python

import requests

def rag_qa(rag_id, query, conversation_id=None):
    url = "http://localhost:8080/snail-ai/open-api/rag/qa/stream"
    headers = {
        "Content-Type": "application/json",
        "Snail-Ai-Auth": "your-token"
    }
    payload = {"ragId": rag_id, "query": query}
    if conversation_id:
        payload["conversationId"] = conversation_id

    response = requests.post(url, json=payload, headers=headers, stream=True)
    full_text = ""

    for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
        if chunk:
            full_text += chunk
            print(chunk, end="", flush=True)

    print()
    return full_text

使用建议

搜索 vs 问答

场景	推荐接口	说明
精确查找文档片段	`rag/search`	返回原始文档片段和评分
自然语言回答	`rag/qa/stream`	AI 基于检索结果生成完整回答
需要引用来源	`rag/search`	可获取文档名称和片段 ID
用户交互式问答	`rag/qa/stream`	支持多轮对话上下文
批量检索	`rag/search`	适合后台批量处理

错误处理

知识库不存在：

json

{
  "code": 0,
  "msg": "知识库不存在",
  "data": null
}

知识库为空（无文档）：

json

{
  "code": 1,
  "msg": "success",
  "data": {
    "results": []
  }
}

查询为空：

json

{
  "code": 0,
  "msg": "query 不能为空",
  "data": null
}

知识库查询 ​

知识库搜索 ​

请求体 ​

curl 示例 ​

响应示例 ​

搜索结果字段 ​

性能指标字段（debug=true 时返回） ​

知识库问答（流式） ​

请求体 ​

curl 示例 ​

响应格式 ​

客户端处理示例 ​

使用建议 ​

搜索 vs 问答 ​

错误处理 ​

知识库查询

知识库搜索

请求体

curl 示例

响应示例

搜索结果字段

性能指标字段（debug=true 时返回）

知识库问答（流式）

请求体

curl 示例

响应格式

客户端处理示例

使用建议

搜索 vs 问答

错误处理