开始使用知识库 API

了解知识库 API 如何组织内容、处理文档以及执行 AI 操作，以便您能够基于该平台构建应用程序。

该 API 支持各类工作流，用于管理收藏集和文档、处理内容以及应用问答、生成摘要、搜索、结构化提取等 AI 功能。通过此页面了解各个模块如何协同工作，然后使用 API 参考获取端点层面的实施细节。

准备事项

请确保您已具备以下条件：

• 访问知识库的权限。
• 已为您的应用程序配置 API 访问权限。
• 拥有某个收藏集的访问权限或者创建收藏集的权限。
• 可用于获取最新端点定义和架构的知识库 API 参考。

如果您尚未配置 API 访问权限，请参阅设置知识库 API 访问权限。

API 的工作原理

典型的知识库 API 工作流遵循以下序列：

身份验证 → 收藏集 → 文档 → 索引 → 推理 → 响应

收藏

收藏集定义了您的应用程序所处理的知识领域。创建收藏集时，返回结果会包含其唯一的命名空间，后续操作需要使用该命名空间。

例如：

{
"namespace": "<collection-namespace>",
"name": "example-collection"
}

请保留收藏集命名空间，用于文档和推理请求。

文档

文档会上传到收藏集并分配唯一的文档标识符。

上传响应会标识该文档，方便您的应用程序跟踪处理进度，并在后续请求中引用该文档。

{
"document_id": "<document-id>",
"document_name": "example.pdf"
}

构建索引

上传文档和索引文档是不同的阶段。

上传是将文件传输到知识库。索引会提取文档内容并做加工处理，以供 AI 操作使用。

您的应用程序应确认处理已完成，然后再针对文档提交推理请求。

推理

推理操作会将知识库 AI 功能应用于已处理的内容。

可用操作包括：

• 问答
• 文档摘要
• 上下文搜索
• 结构化属性提取

使用 API 参考来确定待执行操作对应的端点和请求架构。

响应

推理响应会返回生成的结果，并可以包含支持性归属信息。

根据操作类型不同，归属数据可以标识与结果关联的来源内容、页码以及坐标。由您的应用程序决定如何向用户展示这些信息。

运行基础 API 工作流

最简单的应用程序工作流包括：创建收藏集、添加文档、等待处理完成，再执行推理操作。

了解文档处理机制

文档生命周期会影响您的应用程序何时可以使用已上传的内容。

该区别对于自动化工作流尤为重要。应用程序应检查处理状态，而不是在上传完成后立即发送推理请求。

选择推理操作

根据您的应用程序需要对源内容执行的操作选择对应的功能。

问答

使用问答功能提交有关收藏集或文档内容的自然语言问题。

该 API 同时支持流式与非流式问答。

流式问答会在生成过程中逐步返回响应。适合界面需要逐段显示生成内容的场景。

流式问答还支持控制是否对请求应用自定义指令。您还可以控制是否为流式问答响应生成推理过程。

非流式问答会等待生成全部完成后返回最终响应。适用于应用程序无需显示部分输出的场景。

摘要

使用摘要功能生成文档内容的精简版本。

API 参考定义了当前请求要求以及支持的输入。

上下文搜索

使用上下文搜索来检索与指定搜索文本相关的内容。

这可以帮助应用程序识别相关的来源资料，而无需生成对话式回复。

属性提取

当应用程序需要从文档内容获取结构化数值时使用提取功能。

提取定义可以识别如下信息：

属性名称：contract_value
类型：整数
描述：协议合约价值
提示词：提取以美元为单位的最大协议金额。

返回的结果可以包含提取的值、置信度信息以及来源归属。

控制操作所使用的内容范围

API 提供多种方式来确定哪些内容参与本次请求。

收藏集和文档

使用收藏集和文档标识符，确定一项操作可使用的主要内容。

文档标签

标签与文档关联，而非与收藏集关联。

文档标签仅可通过知识库 API 使用，标准用户界面不予展示。

您可以在受支持操作中使用标签，对请求所考量的文档进行筛选。例如，应用程序可以为一组文档打上财务文档标签，并将问答限制在带有该标签的文档。

附件

附件独立于收藏集文档。

向对话添加附件不会将该文件添加到收藏集。附件仍可与收藏集内容以及聊天历史记录一起，为生成回复提供上下文。

当您的应用程序需要临时或对话专属内容，而又不想将其永久添加到收藏集时，请使用附件相关端点。

使用归属数据

推理响应可以包含归属信息，将生成输出与支持性源内容建立关联。

归属数据可包含如下信息：

• 支持性文本
• 文档信息
• 页码
• 页面坐标

API 将以上信息以数据形式提供。您的应用程序负责决定如何呈现这些信息。

例如，应用程序可以利用返回的坐标来构建源文本高亮体验，以标识生成答案对应的出处位置。

处理访问权限和请求故障

API 各项操作会沿用已验证身份所具备的权限。

如果已认证身份没有访问所请求收藏集、文档或操作的权限，则请求会失败。

排查问题时：

• 查看返回的 HTTP 状态以及响应内容。
• 确认已认证身份可以访问请求资源。
• 确认文档处理已成功完成后再运行推理。
• 确认请求中提供的标识符正确。
• 捕获响应标头中返回的 X-Request-ID。

X-Request-ID 可在整个知识库服务范围内标识请求，协助支持人员排查失败请求。

实施注意事项

• 单次上传请求最多支持 200 个文件。更多文件可以通过后续请求上传。
• 上传与建立索引是相互独立的操作。
• 文档必须进入处理完成状态之后，才可用于推理。
• 附件属于独立资源，不会自动添加到收藏集。
• 标签隶属于文档，受支持操作可使用标签对源内容进行筛选。
• 使用 API 参考作为当前端点、参数、架构以及受支持操作的权威来源。

继续开发

如果您需要可以运行的应用程序示例来演示这些概念，请使用 Python 演示。

开始使用知识库 Python 演示

当您准备实施某项具体操作时，请使用 API 参考。

打开知识库 API 参考