煎蛋 - Gendial

简体中文

English

简体中文

English

Appearance

知识库 API ​

知识库 API 用于从外部系统向 Gendial 知识库写入文档、直接检索知识库，以及删除文档。它适合企业内部系统同步文档，或由业务应用自行完成检索结果的后处理和回答生成。

使用前提 ​

  1. 在 Gendial 中创建知识库。
  2. 在知识库设置中查看或生成 API 密钥。API 密钥只用于该知识库的 API 鉴权，不是用户登录令牌。
  3. 记下知识库 ID（libId）。
  4. 确保知识库已经完成所需的向量化或知识图谱配置。当前直接查询接口支持向量库和知识图谱；文件库直接查询暂不支持。

API 密钥在 HTTP 请求中作为 Bearer Token 发送：

http
Authorization: Bearer <library-api-secret>
Content-Type: application/json

所有请求都发送到 Gendial 后端的 /api 路径。将示例中的 https://your-gendial.example.com 替换为实际的 Gendial 服务地址。

上传或更新文档 ​

POST /api/ingest ​

该接口创建文档或触发已有文档的更新，并异步加入知识库处理队列。请求体必须是 JSON。

字段类型必填说明
libIdstring是知识库 ID，长度 1–48。
docIdstring是文档 ID，长度 1–48。更新时建议保持稳定。
docNamestring是文档名称，长度 1–1024。也用于匹配同名文档。
contentstring否文本内容，最大 10 MB。实际请求还受整个 JSON 请求体约 10 MB 的大小限制。未传 fileUrl 时使用。
fileUrlstring否外部可访问文件 URL。传入后优先于 content。
docDescstring否文档描述，长度 1–1024。
docAliasstring否请求字段，长度 1–1024；当前新建、fileUrl 模式或文本覆盖模式下服务端会将其覆盖为 docName，追加已有文本时不会更新文档别名。
overwriteboolean否仅影响文本内容模式。为 true 时覆盖已有内容；默认情况下，已有同名文档会追加文本。

实际调用时应提供 content 或 fileUrl。使用 fileUrl 时，服务端会从该 URL 下载文件，并始终覆盖匹配的已有文档；文件类型根据 docName 的扩展名推断，服务端会将 docAlias 设置为 docName。使用 content 时，文档按纯文本处理：如果已有匹配文档且未设置 overwrite: true，新内容会追加到原内容之后；如果创建或覆盖文档，服务端同样会将 docAlias 设置为 docName。

文本内容示例 ​

bash
curl -X POST 'https://your-gendial.example.com/api/ingest' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "docId": "product-guide-v1",
    "docName": "product-guide.txt",
    "content": "产品名称：示例产品\n版本：1.0",
    "docDesc": "示例产品使用指南",
    "overwrite": true
  }'

外部文件 URL 示例 ​

bash
curl -X POST 'https://your-gendial.example.com/api/ingest' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "docId": "annual-report-2025",
    "docName": "annual-report-2025.pdf",
    "fileUrl": "https://files.example.com/annual-report-2025.pdf",
    "docDesc": "2025 年度报告"
  }'

成功响应表示请求已接受：

json
{
  "error": "",
  "data": {}
}

这不表示文档已经完成解析或向量化。调用方应通过自己的任务状态机制或后续检索确认处理结果。

直接检索知识库 ​

POST /api/query ​

该接口只执行知识库检索，不负责使用检索结果生成最终答案。一次只能查询一个知识库，当前支持向量库和知识图谱。文件库不支持通过该接口直接查询；调用方可以据此自行排序、过滤、拼接上下文或交给其他模型生成答案。

字段类型必填说明
libIdstring是要查询的知识库 ID，长度 1–48。
querystring是用户问题或检索文本，长度 1–1024。
retrieveDocCountinteger是希望召回的文档/结果数量。
enhanceContextboolean否是否同时补充命中块前后的上下文。
retrieveDocThresholdnumber否向量检索允许的最大 L2 距离阈值；值越小筛选越严格。当前应传正数；传 0 会因服务端默认值逻辑回退为 1.5。
libraryLlmModelstring否长度 1–256。当前直接查询接口不会使用该字段进行重排，保留它仅为兼容请求结构。
retrieveScoreThresholdnumber否文件库检索阈值字段，当前直接查询接口不支持文件库检索，因此不要依赖该字段。
bash
curl -X POST 'https://your-gendial.example.com/api/query' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "query": "示例产品的保修期限是多少？",
    "retrieveDocCount": 4,
    "enhanceContext": true,
    "retrieveDocThreshold": 1.5
  }'

成功响应的外层结构为：

json
{
  "error": "",
  "data": [
    {
      "libId": "library-id",
      "libName": "产品知识库",
      "docResults": [
        {
          "docId": "product-guide-v1",
          "docName": "product-guide.txt",
          "trunkResults": [
            {
              "text": "命中的文本块",
              "context": "包含前后文的上下文",
              "similarity": 0.91
            }
          ]
        }
      ]
    }
  ]
}

常见返回字段如下，具体结果会根据知识库类型和命中结果变化：

  • 知识库项：libId、libName、libType、libDesc、embeddingModel、score、docResults。
  • 文档项：docId、docName、docAlias、docDesc、docType、score、trunkResults。
  • 文本块项：text、context、similarity、score、won；部分结果还可能包含 parentTrunkId。

字段值和分数会根据检索策略和命中结果变化。不要依赖示例中的分数或空数组；没有命中时仍应按 data 数组处理。

删除文档 ​

DELETE /api/ingest ​

按知识库 ID 和文档名称删除文档及其检索数据。

字段类型必填说明
libIdstring是知识库 ID，长度 1–48。
docNamestring是文档名称，长度 1–1024。

请求示例：

bash
curl -X DELETE 'https://your-gendial.example.com/api/ingest' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "docName": "product-guide.txt"
  }'

成功响应：

json
{
  "error": "",
  "data": {}
}

响应、状态码与限流 ​

状态码含义
200请求成功。上传接口表示已接受处理任务，不代表异步解析已经完成。
401缺少 Bearer Token，或 API 密钥不正确。
404知识库或要删除的文档不存在。
413JSON 请求体超过服务端约 10 MB 的大小限制。
422请求体字段缺失、类型错误或超出长度限制。
500服务端处理异常；当前不要对文件库调用直接查询接口。
429请求超过接口限流。

知识库 API 每秒最多处理 20 个请求。批量同步时请在调用方进行限速和重试，并对 401、422 等不可通过重试解决的错误区别处理。

安全建议 ​

  • 不要把 API 密钥提交到代码仓库、前端页面、日志或客户端应用中。
  • 推荐由服务端保存密钥并代理调用知识库 API。
  • 为不同的外部系统使用不同的知识库或密钥管理策略；密钥泄露后应及时在知识库设置中重置。
  • fileUrl 必须是 Gendial 服务端能够访问的地址，并应使用 HTTPS；不要把带有长期有效敏感凭证的 URL 写入日志。
  • 查询结果可能包含知识库中的内部内容，调用方应继续执行自己的访问控制和敏感信息保护。

Last updated: