文档中心

数据智能体

企业知识引擎

企业知识引擎 OpenAPI

本文提供企业知识引擎 OpenAPI 列表，以及 API 相关的术语解释、接入流程、认证验证流程以及错误处理等说明。

API 列表

功能模块	API	说明
知识库	创建知识库	创建一个新的知识库。
	更新知识库	更新知识库信息，包括描述、调度信息等。
	知识库详情	获取知识库详情，包括 ID、操作时间、描述、类型、创建者和调度配置等信息。
	获取知识库列表	获取知识库列表，包含各知识库的 ID、操作时间、描述、类型、创建者和调度配置等信息。
	删除知识库	删除指定的知识库。
文档管理	创建文档	在指定知识库内创建新文档。
	查询文档	分页查询指定知识库中的文档列表。
	文档召回	基于 question 对指定知识库（或 doc_ids）中的文档做语义召回，使用文档元信息（overview / guide）作为向量来源，支持多路 channel 并发召回与融合、相似度阈值过滤、top_n 截断，返回 doc_id 列表及分数。
	批量获取文档信息	批量获取知识库内文档的详细信息。
	批量删除文档	批量根据文档ID删除文档及其关联的Chunk数据。
	删除文档	根据文档ID删除指定文档及其关联的Chunk数据。
	开始解析文档	触发文档解析正式执行任务，将文档内容切分为 Chunk 并建立索引，使其可被检索。
	新增文档版本	将已上传的单个文件作为目标文档的新版本提交。
	查询文档版本设置	查询版本写入策略和版本号规则。
	更新文档版本设置	统一更新版本写入策略和版本号规则；规则变更会重算历史展示版本号。
	查询文档版本列表	查询文档的全部版本及当前生效状态。
	切换文档版本	实时切换生效版本，并在切换后禁用旧版本。
	删除文档版本	删除非生效且非处理中的文档版本。
	获取文档	通过文档 ID 获取知识库内文档内容（如下载文件）。
	编辑文档的配置	编辑知识库内具体文档解析配置，并提交后续执行任务。调用当前接口后，相关任务仅被提交、尚未正式执行，必须继续调用开始解析文档才会真正开始执行。
	创建文件夹	创建一个新的文件夹，可以指定父文件夹ID和文件夹类型。
	查询文件夹列表	获取指定知识库下的所有文件夹列表，以树形结构返回。
	查询知识库目录文件树	获取当前用户可见的知识库目录和文件树，支持名称关键词过滤。
	移动文档或文件夹	将指定文档或文件夹移动到目标父文件夹下。调用当前接口之前，可先调用查询文件夹列表获取可选目标文件夹。
	更新文件夹名称	更新指定文件夹的名称。
	删除文件夹	删除指定文件夹。
	获取文档版本内容	按 doc_id 和 version_id 读取当前租户可访问文档的指定版本 Markdown 内容。
	批量启用或禁用文档	批量启用或禁用文档，也支持启用或禁用指定文档下的 Chunk。调用当前接口之前，可先调用查询文档获取待操作文档。
文件管理	上传文件	上传文件到知识库系统，支持多种文件格式，并返回文件元信息。调用当前接口后，文件尚未开始解析，必须继续调用文件关联知识库完成文件关联知识库和解析参数配置。
切片管理	获取 Chunk 列表	按知识库或文档获取 Chunk 列表，支持关键词、可用状态和排序条件。返回结果包含 Chunk 基础内容、启用状态、额外信息等元数据。
	修改 Chunk	修改指定知识库中文档的Chunk内容，支持更新文本、元数据等信息。
	知识库检索	基于语义或关键词在知识库中检索相关文档片段，支持知识元信息过滤筛选。请求可通过 label_value_ids、label_values、enable_filters 和 extra 控制标签、权限、过期时间和扩展元信息过滤；响应返回知识展示名、综合相似度、向量相似度、关键词相似度和重排分等 Chunk 相似度元信息。
	多知识库检索	基于语义或关键词并行检索多个知识库，并融合返回相关文档片段。接口沿用知识库、文档、标签、权限和过期时间过滤规则。
	批量导入 QA 类知识	通过已上传的表格文件批量导入 QA 库、Query 库或术语库知识。
	批量导出 QA 类知识	批量导出 QA 库、Query 库或术语库中的知识条目，支持按条目 ID 精确导出或按查询条件导出全部匹配内容。接口返回异步导出任务 ID，后续可在下载任务列表中查看任务结果。
	查询 QA 类知识导入任务	分页查询 QA 库、Query 库或术语库的批量导入任务进度，返回任务状态、成功数量、失败数量和失败文件下载地址。通常在调用批量导入 QA 类知识后使用当前接口跟踪导入结果。
文件转文档	文件关联知识库	将已上传的文件关联到指定知识库，并配置解析参数。调用当前接口之前，应先调用上传文件；完成当前接口后，相关任务仅被提交、尚未正式执行，还必须继续调用开始解析文档才会真正开始执行。
文件转文档	读取表格表头	读取上传的表格文件的表头信息，用于后续数据映射配置
查询与图谱检索	图谱检索	对指定图谱执行向量+图混合检索，返回召回内容，不经过大模型。
会话管理	创建会话	创建一个新的对话会话，用于记录用户与AI应用之间的交互历史。
	拉取会话列表	分页查询指定对话下的所有会话记录，支持按来源类型筛选。
	拉取会话中聊天内容	分页获取指定会话中的历史聊天消息，按时间顺序排列。
	检索应用调用	调用已发布检索应用，返回纯召回结果。
文档权限管理	查询标签列表	分页查询当前租户下的标签列表，支持关键词、知识库和自动标签筛选。
	新建标签	新建文档/知识库标签。
	绑定或创建标签	为指定文档绑定标签；当标签值不存在时可按请求内容创建标签值后绑定。可先调用新建标签创建标签，也可调用为文档打标签仅执行已有标签绑定。
	为文档打标签	为指定文档添加标签。
	批量为文档打标签	批量为多个文档绑定标签，并返回每个文档的处理结果。调用前应先通过新建标签创建标签。
	移除文档标签	从指定文档或知识库中移除标签。
	移除指定文档标签	从指定文档中移除指定标签值。调用方需要租户管理员权限。
	删除标签	删除指定的标签。
	设定文档有效期	设置单个文档的有效期，并可选择过期后自动删除。
	批量设定文档有效期	批量设置多个文档的有效期，并可选择过期后自动删除。
	获取文档标签	设置单个文档的有效期，并可选择过期后自动删除。
	获取 QA 标签	按 qa_id 从 sophon 查询单条 QA 的标签,并把 sophon 返回的 label_id / label_value_id 映射回 verag 的 label_name / value。仅用于 QA 系(QA / Cache / Term)库。
	下载 QA 标签 CSV	导出当前租户下全部标签及其值,一行一个 label。tag 列给出与 QA Excel 导入 tag 字段一致的字符串(如 `城市:上海,北京`),label_type 列标注单选/多选。返回 UTF-8(BOM) 编码的 CSV。需当前用户具有知识库模块的读权限(与 kb/list 一致)。
	根据标签ID获取标签详情	按标签ID获取标签详情和值列表。
	根据标签名称获取标签详情	按标签名称获取标签详情和值列表。调用方需要租户管理员权限。
混合检索	查询表结构	查询底层搜索引擎的表结构，返回主键、字段定义、向量字段和全文检索字段配置。
	追加混合检索字段	为已有底层搜索引擎的表追加字段，并可同步声明向量检索字段和全文检索字段。调用前可先通过查询表结构查询当前表结构。
	删除混合检索字段	删除底层搜索引擎的表中的单个字段。调用前应确认目标表和字段存在，可先调用查询表结构查看当前表结构。
	批量删除混合检索字段	批量删除底层搜索引擎的表中的多个字段。调用前应确认目标表和字段存在，可先调用查询表结构查看当前表结构。
	按过滤条件删除数据	按 DSL 过滤条件删除底层搜索引擎的表中的数据。调用前可先通过混合召回验证过滤条件能精确命中待删除数据，避免误删。
	创建表结构	创建底层搜索引擎的表结构，声明字段定义、向量检索字段和全文检索字段。写入数据前应先调用当前接口完成建表，再调用写入数据写入数据。
	写入数据	向底层搜索引擎的表写入数据。调用当前接口之前，应先调用创建表结构创建表结构，或确认目标表已经存在；写入后可调用混合召回验证召回效果。
	删除数据	按数据 ID 删除底层搜索引擎的表中的数据。调用前可通过创建表结构确认目标表存在，并确认 ID 来自写入数据已写入的数据。
	混合召回	基于 DSL 对底层搜索引擎的表执行混合召回查询。调用当前接口之前，应先通过创建表结构完成表结构创建，并通过写入数据写入可召回数据。
版本管理	开启版本管理	为指定文档创建版本组并开启版本管理。
	新增版本类型	为指定版本组设置版本类型。
	获取版本列表	获取指定版本组的版本列表与详情信息。
系统权限管理	批量添加租户用户	批量添加用户到当前租户。
	从租户移除用户	从当前租户批量移除用户。调用方需要管理员权限，且不能移除管理员用户。
	更新用户状态	启用或停用租户用户。调用方需要管理员或所有者权限，并受管理员、所有者和本人操作限制约束。
	模块批量授权/取消模块权限	批量授权/取消模块权限（支持用户、角色、部门）。
	批量查询当前用户资源权限	按数值 resource_id 批量查询当前认证用户的有效资源权限，不查询上游资源目录。
	查询当前用户授权资源 ID 范围	按资源类型和动作查询当前认证用户可访问的数值 resource_id；租户管理员返回 unrestricted=true。
	资源权限授权/取消授权	资源权限授权/取消授权。
个人知识空间内容	获取个人知识库原文件	获取当前用户个人知识库文档的原文件下载地址；飞书文档返回飞书原文地址。
	获取个人知识库 Markdown	获取当前用户个人知识库文档的可阅读 Markdown 地址；产物未就绪时返回空地址。
	个人知识库检索	在当前应用 Token 绑定用户的个人知识库内召回相关 Chunk；支持限定文档和召回参数。
个人知识空间文档	获取个人知识库文档列表	分页查询当前应用 Token 绑定用户导入的个人知识库文档，结果不包含文件夹。
个人知识空间导入	导入个人知识库文档	上传文件到当前应用 Token 绑定用户的个人知识库，并使用服务端固定解析配置提交解析任务。
结构化知识库导入	上传结构化文件	上传 CSV 或 Excel 文件，返回后续创建资产和导入使用的 file_id。
	发起结构化数据导入	自动确保 OpenSearch 索引就绪后，发起本地文件或 Prep 数据集导入并返回统一任务引用。
	查询结构化任务	使用统一 task_ref 查询本地文件导入、Prep 数据集导入或异步删除任务状态。
	创建结构化数据资产	创建 CSV、Excel、ClickHouse 或 Hive 数据资产及字段草稿。
结构化知识库管理	创建结构化知识库	创建结构化知识库，并为当前调用者登记创建者权限。
	查询结构化知识库列表	按名称关键词和状态分页查询当前调用者有权访问的结构化知识库。
	查询结构化知识库目录	查询结构化知识库目录树，返回与知识库同名的根目录及其子目录。
	查询结构化数据资产列表	按目录、数据来源、处理状态或名称关键词分页查询结构化数据资产。
	查询结构化数据资产详情	查询指定数据资产的来源、状态、文件大小、行数和最近错误等公开元数据。
	删除结构化数据资产	删除数据资产及其 OpenSearch 索引；相同请求可安全重试。
	删除结构化知识库	异步删除知识库及其全部数据资产和索引，并返回任务引用。
结构化知识库查询	查询结构化数据行	按关键词、排序和分页条件查询结构化数据行。
	查询结构化数据行详情	根据稳定 row_key 查询单条结构化数据。
	新增结构化数据行	向已就绪的结构化数据资产新增一行数据。
	编辑结构化数据行	根据稳定 row_key 局部更新一行数据，未传字段保持原值。
	删除结构化数据行	根据稳定 row_key 删除一行数据；目标行已不存在时仍按幂等成功返回。
	更新结构化数据表结构	新增字段或编辑启用、过滤、返回、向量、展示名和描述配置；不支持物理删除字段、字段改名和修改数据类型。
	查询结构化数据表结构	查询逻辑字段、过滤/向量/返回能力和 OpenSearch 索引就绪状态，不暴露底层 mapping。
	查询字段枚举值样例	查询指定逻辑字段的枚举样例和出现次数，供过滤条件值选择使用。
	召回结构化知识	按单表范围、精确过滤、语义字段、返回字段和排序参数执行混合检索并返回数据行。
账号中心	批量新建用户	批量新建用户账号，支持邮箱、手机号、状态和自定义属性。

术语解释

字段中文	字段英文	解释
集团	X-Org	SaaS 环境上为您开通的一个主账号即一个集团，集团之间彼此数据、功能、用户完全独立。私有化部署环境，如开通多集团，则一个环境支持多个集团，不同集团之间的数据完全隔离；如未开通多集团，则一套环境为一个集团。
项目	X-Tenant	一个集团下可以创建多个项目，一个集团下，用户可以通过权限设置来限定可以访问的项目，API 调用时项目是必传字段。
应用	--	调用 API 的基本单位。调用 API 时需要先登录企业知识引擎控制台，在开放平台 > 应用管理功能中创建应用，并获取 AccessKey。

接入流程

企业知识引擎（VeRAG）应用认证是一种基于 Token 的 API 访问认证机制。用户通过 Web 界面创建应用并获取唯一的 Token（AK），然后使用该 Token 调用授权的业务 API 接口。

步骤一：创建应用并获取 Token

登录营销 Agent 平台。
在左侧导航栏进入企业知识引擎。
在企业知识引擎的左侧导航栏，选择项目中心 > 开放平台 > 应用管理。
在应用管理页面右上角，单击新建应用。

在新建应用页面，完成以下配置，并单击保存。

模块	配置项	说明
基础信息	应用名称	自定义名称，标识当前应用。
基础信息	应用可使用的API	选择当前应用可调用的企业知识引擎 OpenAPI 范围。
调用OpenAPI认证方式	访问可授权项目	指定当前应用可授权的项目。
调用OpenAPI认证方式	关联用户	指定访问 API 时的用户身份。

（可选）创建完成的应用可在应用列表查看，在该列表中，可选择以下操作。
- 在列表中可查看应用的基本信息，包括名称、关联 API、关联用户等信息。
- 在页面右上角，支持切换应用的查看方式（表格或卡片）。
- 在操作列单击编辑，支持修改当前应用的配置信息。
- 在操作列单击删除，可删除不再需要的应用。
  注意
  应用一旦删除无法恢复，请谨慎操作。
在应用列表中，获取应用 Token。
后续调用 OpenAPI 时需要传入所使用应用的 Token。

Token 信息说明：
字段
说明
Token (AK)
访问密钥，用于 API 认证
授权租户 (tenant_ids)
Token 可访问的租户/项目 ID 列表
授权 API (api_paths)
Token 可访问的 API 路径列表

字段	说明
Token (AK)	访问密钥，用于 API 认证
授权租户 (tenant_ids)	Token 可访问的租户/项目 ID 列表
授权 API (api_paths)	Token 可访问的 API 路径列表

步骤二：使用 Token 调用 API

您可以参考以下参数说明与调用示例，了解如何使用 Token 调用 API。

调用业务 API 时，需要在请求头中添加以下信息：

Header	取值格式	说明
Authorization	`Bearer <token>`	认证 Token，格式为 Bearer + 空格 + Token
X-Org	`<org_id>`	组织 ID
X-Tenant	`<tenant_id>`	租户/项目 ID（必须在授权的 tenant_ids 列表中）
X-User-Id	`<user_id>`	条件必填。应用用户模式为「请求时指定用户」时可用于指定本次调用的下游用户，优先级高于 X-User；系统会校验该用户属于当前 X-Org 和 X-Tenant 且状态有效
X-User	`<user_account>`	条件必填。应用用户模式为「请求时指定用户」时可用于指定本次调用的下游用户；若同时传入 X-User-Id，以 X-User-Id 为准。「关联指定用户」模式无需传入，传入也会被忽略

HTTP 请求示例

GET {base_url}/marketing_agent/api/v2/open_application/openapi/{product}/{api_path}
Authorization: Bearer a1b2c3d4e5f6g7h8xxxx
X-Org: 1
X-Tenant: 1

{base_url}：API 请求 URL，SaaS 环境固定为 https://console.volcengine.com。
{product}：产品名，如企业知识引擎为 VeRAG。
{api_path}：接口路径，可通过对应的 API 文档获取，如「查询文档」接口路径为 /document/list。

Python 示例

import requests

# 配置
BASE_URL = "https://your-api-domain.com"
TOKEN = "{your_token}"
ORG_ID = 1
TENANT_ID = 1

# 产品和接口配置
product = "VeRAG"  # 产品名，如企业知识引擎为 VeRAG
endpoint = "{api_path}"  # 接口路径，可通过对应的 API 文档获取

# 请求头
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-Org": str(ORG_ID),
    "X-Tenant": str(TENANT_ID),
    "Content-Type": "application/json"
}

# 发送请求
response = requests.get(
    f"{BASE_URL}/marketing_agent/api/v2/open_application/openapi/{product}/{api_path}",
    headers=headers
)

print(response.json())

cURL 示例

curl -X GET "https://your-api-domain.com/marketing_agent/api/v2/open_application/openapi/{product}/{api_path}" \
  -H "Authorization: Bearer {your_token}" \
  -H "X-Org: 1" \
  -H "X-Tenant: 1" \
  -H "Content-Type: application/json"

以查询文档接口为例，cURL 调用示例如下：

curl --location 'https://your-api-domain.com/marketing_agent/api/v2/open_application/openapi/VeRAG/document/list?kb_id=89&page=1&page_size=10' \
--header 'X-Org: 1' \
--header 'X-Tenant: 1' \
--header 'Authorization: Bearer {your_token}'

认证验证流程

当使用 Token 调用 API 时，系统会进行以下验证：

错误处理

常见错误信息、原因以及解决方案说明如下：

错误信息	原因	解决方案
`Authorization missing`	未提供 Authorization Header	添加 Authorization Header
`Please check your authorization format`	Authorization 格式错误	使用 `Bearer <token>` 格式
`Need bearer auth`	未使用 Bearer 认证类型	使用 `Bearer` 认证类型
`no found user app about token`	Token 无效或不存在	检查 Token 是否正确
`Please check your org_id and tenant_id`	org_id 或 tenant_id 缺失或格式错误	检查 X-Og 和 X-Tenant Header
`no found tenant config about token`	Tenant ID 未授权	使用授权列表中的 tenant_id
`the route path is UnAuthorized`	API 路径未授权	确认该 API 已在应用中授权

安全建议

妥善保管 Token
Token 相当于密码，请勿泄露或提交到公开仓库
最小权限原则
只授权必要的 API 路径和租户 ID
定期轮换
建议定期通过界面删除旧应用并创建新应用以更新 Token
使用 HTTPS
确保所有 API 调用都通过 HTTPS 进行，防止 Token 被窃取
及时回收
不再使用的应用应及时删除，避免 Token 泄露风险

最近更新时间：2026.09.17 20:43:15

这个页面对您有帮助吗？

有用

无用

数据智能体

步骤一：创建应用并获取 Token #

步骤二：使用 Token 调用 API #

认证 Header 配置 #

HTTP 请求示例 #

Python 示例 #

cURL 示例 #

步骤一：创建应用并获取 Token

步骤二：使用 Token 调用 API

认证 Header 配置

HTTP 请求示例

Python 示例

cURL 示例