该包包含脚本和配置，用于演示收藏集管理、文档处理、推理以及相关 API 操作。
上次更新日期：
2026年10月12日
运行、检查并调整常用知识库 API 工作流的可用 Python 实施。
Python Demo 可为应用程序开发提供功能完整的起点。使用完整工作流，查看收藏集创建、文档处理和 AI 推理如何协同运作，然后浏览各个独立脚本，执行特定收藏集和推理操作。
准备事项
请确保您已具备以下条件：
- 拥有知识库 API 的访问权限。
- 对您的应用程序进行身份验证所需的凭据。
- Python 3.7 或更高版本。推荐使用 Python 3.11 或更高版本。
- 一份可用于完整演示工作流的 PDF 文件。
如果您尚未配置 API 访问权限，请参阅设置知识库 API 访问权限。
下载并设置 Python Demo
创建虚拟环境：
python3 -m venv venv
激活环境：
- 在 macOS 或 Linux 系统上：
source venv/bin/activate - 在 Windows 系统上：
venv\Scripts\activate
安装依赖项：
pip install --upgrade pip
pip install -e .
将所需的 API 凭据和服务配置添加到 config.yaml。
在运行示例脚本之前，请先切换到 python 次文件夹。
该演示使用 requests、pyyaml 和 tqdm。凭据存储在 config.yaml 中，身份验证令牌由程序自动管理。
请勿将 config.yaml 或生成的 .token 文件提交到源代码管理。
运行完整工作流
运行：
python knowledgebase.py
要使用指定的 PDF：
python knowledgebase.py --document=<path-to-pdf>
该演示程序执行以下操作：
- 通过 API 进行身份验证。
- 创建名为 demo-collection 的收藏集。
- 上传 PDF 文件。
- 监控文档状态，直至索引完成。
- 对已处理的文档运行推理请求。
上传和索引是文档摄取流程中两个独立环节。索引会提取文档内容，使其可供 AI 操作使用。
如果您未指定 PDF，演示程序将从包的 documents 目录中选取一份文件。如果文档处理在 5 分钟内未达到完成状态，则会超时。
注释
完整工作流会创建一个名为 demo-collection 的收藏集，并向其中上传一份 PDF。工作流执行完毕后，演示程序不会删除该收藏集或已上传的文档。
探索收藏集操作
运行完整工作流之后，可以使用独立脚本体验各类具体 API 操作。
创建收藏集
python collection.py --action create --name <collection-name>
收藏集名称最多可包含 255 个字符。
列出收藏集
python collection.py --action list
出现提示时，请选择是要列出由您创建、由您共享还是由他人共享的收藏集。
共享收藏集
python collection.py --action share --collection-id <collection-id>
出现提示时，输入需要授予读取或写入权限的电子邮件地址。
上传文档
python collection.py --action upload --collection-id <collection-id> --path=<path-to-file-or-directory>
该脚本可以上传单个文件，也可以上传指定目录下的多个文档。
列出收藏集中的文档
python collection.py --action get_documents --collection-id <collection-id>
检查文档处理状态
python collection.py --action get_status --document-id <document-id>
演示程序将这些操作作为独立示例提供，您可以检查并修改，无需依赖完整工作流。
探索推理操作
推理示例需要收藏集 ID 和文档 ID。使用收藏集脚本来识别它们：
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
问答
列出您的收藏集和文档，然后运行问答示例：
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --questionAnswer
出现提示时，输入收藏集 ID、文档 ID 和问题。
文档摘要
确认收藏集和文档，然后运行摘要示例：
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --summarize
出现提示时，输入收藏集 ID 和文档 ID。
上下文搜索
确认收藏集和文档，然后运行上下文搜索示例：
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --context-search
出现提示时，输入收藏集 ID、文档 ID 和搜索文本。
属性提取
确认收藏集和文档，然后运行提取示例：
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --extract
出现提示时，输入收藏集 ID、文档 ID、属性名称、提取提示词、数据类型以及可选描述信息。
使用 API 继续构建
Python Demo 提供的是可行的实施模式，而不是完整的 API 文档。
请参阅知识库 API 入门指南，了解 API 资源模型、文档生命周期、推理行为以及响应处理方式。
当您需要当前的端点路径、参数、请求和响应架构以及状态信息时，请使用知识库 API 参考。
故障诊断
演示程序会将详细诊断信息写入以下位置：
logs/knowledgebase-demo.log
日志文件记录 DEBUG 级别的信息，而控制台显示 WARNING 级别及以上的消息。
如果某项操作失败：
- 查看 logs/kinowledgebase-demo.log，获取请求与身份验证详细信息。
- 验证 config.yaml 中的各项设置。
- 确认您所使用的 PDF 文件存在且可正常访问。
- 确认应用程序已为您的组织配置正确的服务端点。
- 确认已认证身份有权访问所请求的资源。
- 对于 API 故障，如果响应标头中返回 X‑Request‑ID，请将其保留。技术支持人员可借助该标识符追踪请求。
实施注意事项
- 完整工作流仅支持 PDF 文件。
- 配置 API 访问权限后，演示程序会自动管理身份验证令牌。
- API 各项操作会沿用已验证身份所具备的权限。
- 源代码软件包包含区域端点发现功能，但生产环境端点取值应参阅当前的知识库 API 文档，而非该演示程序自带的旧版数值。
