AI 文档知识库问答

围绕已上传资料进行连续问答，并返回可核对的引用来源。
详情页：https://www.gugudata.com/api/details/knowledge-chat

当前接口契约

接口详情：https://www.gugudata.com/api/details/knowledge-chat

功能说明

上传企业制度、产品说明、协议和帮助文档即可构建专属知识库；

支持 PDF、TXT、Markdown、HTML 和 DOCX 常见文档格式；

支持按知识库与业务分组管理资料，适合多产品和多项目使用；

支持连续追问并保持会话上下文，便于构建自然的问答体验；

回答同步提供引用来源与内容片段，便于核对信息依据；

支持标准 JSON 与 SSE 流式返回，兼顾完整结果和实时展示；

兼容 OpenAI Chat Completions 调用方式，便于现有应用接入；

返回文档处理状态与内容片段数量，便于确认资料是否可用于问答；

支持删除指定文档和会话，方便维护知识库资料与对话记录；

适合智能客服、开发者门户、内部制度查询和企业资料检索；

请求参数

参数	类型	必填	默认值	说明
knowledge_base_id	string	是	default	知识库标识，路径参数，最长 80 个字符。
appkey	string	否	无	APPKEY，可通过 Query、JSON Body、Header 或 Bearer 传递。 AppKey 整体必填；在本操作已声明支持的鉴权位置任选一个提供，本位置无需重复填写。多处填写时须一致。
model	string	否	gugudata-knowledge-chat	固定为 gugudata-knowledge-chat。
messages	array	是	无	消息数组，最多 20 条；最后一条必须为 user 消息。
thread_id	string	否	无	会话标识，不传时创建新会话，最长 120 个字符。
tenant_id	string	否	default	客户侧业务分组标识，默认 default，最长 80 个字符。
stream	boolean	否	false	是否使用 SSE 流式响应，默认 false。
top_k	integer	否	6	引用片段数量，范围 1 至 12，默认 6。

正常响应字段

字段	类型	说明
id	string	当前回答消息标识。
object	string	OpenAI 兼容响应对象类型。
thread_id	string	当前对话会话标识。
choices[0].message.content	string	基于知识库资料生成的回答。
sources	array	回答引用的文档来源与内容片段。
usage	object	本次请求的使用量摘要。

业务状态说明

业务状态码	业务状态码解释	备注
100	请求成功	接口正常返回
501	参数错误	请检查请求参数、文件大小或文件格式
504	APPKEY 错误	请检查传递的 APPKEY 是否正确
-1	请求失败	知识库处理或问答过程中发生异常

常见问题

怎么把文档加入知识库？上传后就能提问吗？

先调用文档上传接口，用 multipart/form-data 把文件提交到指定知识库。支持 PDF、TXT、Markdown、HTML 和 DOCX，单次最多 5 个文件，单文件最大 20 MB。逐个查看返回的 index_status，显示 ready 后即可用该文件提问。问答时使用上传时相同的 tenant_id 和 knowledge_base_id。

发起知识库问答时，请求体怎么写？

向问答接口发送 JSON 请求，在 URL 路径中填写 knowledge_base_id，并使用该接口的 AppKey。把问题放在 messages 数组的最后一条消息，role 设为 user，content 填写问题文本。messages 最多 20 条。

如何围绕上一轮回答继续追问？

首次提问可以省略 thread_id。收到回答后，保存响应中的 thread_id。后续在同一业务分组、同一知识库中提问时，把该值放回请求体，接口会沿用该会话的近期上下文。开始新话题时省略 thread_id 即可创建新会话。

怎样核对回答的引用来源？找不到依据时会怎样？

读取 choices[0].message.content 中的回答，按 [1]、[2] 等编号对应 sources 数组中的第 1、第 2 条。每条来源可查看文档名称 source_name、位置 location 和引用片段 snippet。资料不足时，接口会提示未找到足够依据。可以补充相关文档并确认已入库，再重新提问。

怎样边生成边展示回答？

在正式请求体中设置 stream=true，接口通过 SSE 逐段返回回答。按顺序拼接 choices[0].delta.content，在最终数据块读取 sources 和 usage。收到 data: [DONE] 表示流正常结束。省略 stream 或设为 false 时，一次返回完整 JSON。

Demo 和正式接口有什么区别？

Demo 无需 AppKey，供接口请求测试和开发调试使用。它使用公开示例文档和固定问题，返回与正式接口非流式模式一致的核心 JSON 字段，包括回答和引用来源。正式接口需使用对应的 AppKey，可基于自己上传的文档提问，并选择 JSON 或 SSE 返回。

入参与出参补充

正式问答入参

字段	补充说明
`knowledge_base_id`	在 URL 路径中填写，例如 default。问答时应与上传文档时的知识库一致。
`appkey`	四种位置任选一种；同一请求在多处提供时，值必须一致。推荐使用 X-GUGUDATA-APPKEY 请求头。
`model`	省略时使用 gugudata-knowledge-chat。
`messages`	至少 1 条，每条必须包含 role 和 content。role 支持 user、assistant、system。content 支持纯文本或文本项数组，每个文本项须提供 type=text 和 text。单条文本最多 2000 字符，所有消息文本合计最多 12000 字符，整个 JSON 请求体最多 64 KiB。最后一条 user 消息是本轮问题，之前的 user 和 assistant 消息可提供上下文。
`thread_id`	继续对话时使用上次响应中的 thread_id，并保持业务分组和知识库一致。
`tenant_id`	用于区分项目、产品或客户等业务分组。问答与上传应使用同一个分组。
`stream`	false 返回完整 JSON。true 返回 text/event-stream，依次读取 choices[0].delta.content；成功时在终块读取 sources 和 usage，随后收到 data: [DONE]。
`top_k`	表示请求检索的来源片段数量。实际返回数量可少于该值，详见 sources。

正式问答出参

字段	补充说明
`id`	标识本次回答。继续对话请使用 thread_id。
`object`	非流式为 chat.completion；SSE 数据块为 chat.completion.chunk。
`thread_id`	继续追问时把此值放回请求体。Demo 返回的会话标识仅用于演示。
`choices[0].message.content`	非流式响应的完整回答。正文中的 [1]、[2] 等编号对应 sources 中的第 1、第 2 条。
`sources`	正文引用编号从 1 开始，对应数组中的位置。资料不足时可能返回空数组；SSE 模式在成功终块中返回。
`usage`	包含输入、输出和合计 Token 数。服务未提供相应计数时，值为 0。SSE 模式在成功终块中返回。
`created`	回答或流式响应的创建时间，Unix 时间戳，单位为秒。
`model`	本次问答使用的模型标识。
`knowledge_base_id`	本次查询使用的知识库标识。
`choices[0].message.role`	非流式回答的角色，值为 assistant。
`choices[0].finish_reason`	非流式成功响应为 stop。SSE 增量块中为 null，成功终块中为 stop。
`choices[0].delta.content`	仅 SSE 文本增量块返回，按接收顺序拼接得到回答。
`sources[].document_id`	引用片段所属文档的标识，对应上传响应中的 document_id。
`sources[].chunk_id`	文档中的引用片段标识。
`sources[].source_name`	来源文档名称。
`sources[].location`	引用片段在文档中的位置标识，例如 page:8 表示第 8 页。
`sources[].score`	片段与问题的相关性分值，范围为 0 至 1。
`sources[].snippet`	用于核对引用的文本片段，最多 240 个字符。
`usage.prompt_tokens`	输入 Token 数。
`usage.completion_tokens`	输出 Token 数。
`usage.total_tokens`	输入和输出 Token 数之和。

请求参数

Query 参数

Header 参数

Body 参数application/json必填

示例

{
    "appkey": "{{appkey}}",
    "model": "gugudata-knowledge-chat",
    "messages": [
        {
            "role": "user",
            "content": "请根据已上传的文档回答，并标注引用来源。"
        }
    ],
    "tenant_id": "default",
    "thread_id": "",
    "stream": false,
    "top_k": 6
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

非流式请求返回 JSON；流式请求返回 SSE，并在完整成功后发送 [DONE]。

Bodyapplication/json

示例

{
    "id": "string",
    "object": "chat.completion",
    "created": 0,
    "model": "gugudata-knowledge-chat",
    "thread_id": "string",
    "knowledge_base_id": "string",
    "query": "string",
    "choices": [
        {
            "finish_reason": "stop",
            "message": {
                "role": "assistant",
                "content": "string"
            },
            "index": 0
        }
    ],
    "sources": [
        {
            "snippet": "string",
            "score": 0,
            "document_id": "string",
            "location": "string",
            "chunk_id": "string",
            "source_name": "string"
        }
    ],
    "usage": {
        "total_tokens": 0,
        "completion_tokens": 0,
        "prompt_tokens": 0
    }
}

🟠400请求参数错误，业务码 501。

🟠401APPKEY 缺失或无效，业务码 504。

🟠403订单已到期或调用额度耗尽，业务码 503 或 505。

🟠404资源不存在。请求路径不存在。

🟠405请求方法不允许。当前路径不支持该 HTTP 方法。

🟠415请求内容类型不支持。上传或请求体的内容类型不符合接口要求。

🟠429请求频率受限，业务码 502。

🔴500服务内部错误，业务码 900。

🔴503知识库服务暂时不可用，业务码 901。

当前接口契约#

功能说明#

请求参数#

正常响应字段#

业务状态说明#

常见问题#

怎么把文档加入知识库？上传后就能提问吗？#

发起知识库问答时，请求体怎么写？#

如何围绕上一轮回答继续追问？#

怎样核对回答的引用来源？找不到依据时会怎样？#

怎样边生成边展示回答？#

Demo 和正式接口有什么区别？#

入参与出参补充#

正式问答入参#

正式问答出参#

请求参数

请求示例代码

返回响应

当前接口契约

功能说明

请求参数

正常响应字段

业务状态说明

常见问题

怎么把文档加入知识库？上传后就能提问吗？

发起知识库问答时，请求体怎么写？

如何围绕上一轮回答继续追问？

怎样核对回答的引用来源？找不到依据时会怎样？

怎样边生成边展示回答？

Demo 和正式接口有什么区别？

入参与出参补充

正式问答入参

正式问答出参