探索相关文件
接口说明
使用文件树、搜索、文件或相关文件接口返回的可读取 fileId。响应按照请求的关系层数和数量上限返回相关文件。
接口信息
| 字段 | 值 |
|---|---|
| 方法 | GET |
| 路径 | /openapi/v2/knowledge-bases/{knowledgeBaseId}/graph/expand |
| Operation ID | expandGraph |
| 鉴权 | Bearer OpenAPI key |
入参
| 名称 | 位置 | 必填 | 类型 | 示例 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | knowledge-base-11111111-1111-4111-8111-111111111111 | 知识库 API 返回的知识库标识。 |
fileId | query | 是 | string | source-file-11111111-1111-4111-8111-111111111111 | 可读取文件标识。 |
depth | query | 否 | 0 | 1 | 2 | 1 | 需要探索的关系层数。 |
fanout | query | 否 | integer | 10 | 每个已探索文件最多返回的相关文件数量。省略时使用当前部署配置。 |
limit | query | 否 | integer | 10 | 最多返回的记录数量。部署环境可能采用更低的上限。 |
cursor | query | 否 | string | cursor_123 | 当前接口返回的下一页分页标记。 |
请求体
这个接口没有请求体。
请求示例
bash
curl -X GET "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-11111111-1111-4111-8111-111111111111&depth=1&fanout=10&limit=10" \
-H "Authorization: Bearer <openapi-key>"成功响应
200
返回指定起点的相关文件和关系详情。
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
activeContentRevision | 是 | integer | 当前可读取知识库内容的修订号。 |
seedFile | 是 | object | 选作关系探索起点的当前可读取文件。 |
relationships | 是 | array<RelatedFile> | 本次结果中找到的相关可读取文件。 |
graphPaths | 是 | array<string> | 位于 _graph/ 下、可以通过按路径读取正文接口打开的关系数据文件。 |
nextCursor | 是 | string | null | 当前关系接口返回的分页标记。只能在探索起点和可读取知识库版本不变时继续使用；被拒绝时请移除 cursor 并重新开始。 |
resultSummary | 是 | object | 当前结果的数量、分页情况和说明。 |
成功响应示例
json
{
"activeContentRevision": 1,
"seedFile": {
"activeContentRevision": 1,
"fileId": "source-file-11111111-1111-4111-8111-111111111111",
"knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111",
"sourceFileId": "source-file-11111111-1111-4111-8111-111111111111",
"path": "pages/guide.md",
"fileKind": "page",
"contentType": "text/markdown; charset=utf-8",
"sizeBytes": 2048,
"okfType": "Guide",
"title": "Verified guide",
"description": null,
"tags": [
"guide",
"policy"
],
"frontmatter": {
"okf_version": "0.2",
"type": "Guide",
"title": "Verified guide",
"tags": [
"guide",
"policy"
],
"sources": [
{
"id": "source-a",
"resource": "references/source-a.md"
}
],
"generated": {
"by": "publisher:example",
"at": "2026-06-17T00:00:00Z"
},
"verified": [
{
"by": "human:reviewer",
"at": "2026-06-17T01:00:00Z"
}
],
"status": "stable",
"stale_after": "2026-12-31"
},
"okfSignals": {
"effectiveStatus": "stable",
"trustTier": "human-reviewed",
"isStale": false,
"staleAfter": "2026-12-31",
"generatedAt": "2026-06-17T00:00:00.000Z",
"generatedAtSource": "generated",
"latestVerifiedAt": "2026-06-17T01:00:00.000Z",
"sourceCount": 1
},
"deletable": true,
"contentAvailable": true,
"readActions": {
"fileDetailById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111",
"fileContentById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/content",
"fileContentByPath": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fguide.md",
"relatedFilesById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/related",
"graphExpansionByFileId": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-11111111-1111-4111-8111-111111111111",
"sourceFileStatusById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111"
}
},
"relationships": [
{
"activeContentRevision": 1,
"fileId": "source-file-22222222-2222-4222-8222-222222222222",
"sourceFileId": "source-file-22222222-2222-4222-8222-222222222222",
"path": "pages/reference.md",
"title": "Reference",
"relationType": "same_specific_subject",
"direction": "outgoing",
"fromFileId": "source-file-11111111-1111-4111-8111-111111111111",
"relationshipDepth": 1,
"reason": "Both files share body-derived subjects.",
"contentAvailable": true,
"readActions": {
"fileDetailById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222",
"fileContentById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222/content",
"fileContentByPath": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Freference.md",
"relatedFilesById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222/related",
"graphExpansionByFileId": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-22222222-2222-4222-8222-222222222222",
"sourceFileStatusById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-22222222-2222-4222-8222-222222222222"
}
}
],
"graphPaths": [
"_graph/by-file/handbook/guide.json",
"_graph/by-file/reference.json"
],
"nextCursor": null,
"resultSummary": {
"relationshipCount": 1,
"hasMore": false,
"depth": 1,
"fanout": 10,
"meaning": "Related files were found. Read the returned files before using their content."
}
}错误码
下表列出这个接口已声明的全部错误响应。
| HTTP 状态 | 错误码 | 说明 |
|---|---|---|
| 401 | UNAUTHORIZED | Bearer API key 缺失、格式错误、未知、已撤销或已删除。 |
| 404 | NOT_FOUND | 请求的资源不存在。 |
| 422 | VALIDATION_ERROR | 请求未通过校验。 |
| 429 | RATE_LIMITED | 请求超过当前配置的速率限制。 |
| 500 | INTERNAL_ERROR | API 遇到内部错误。 |
| 503 | DATABASE_REPOSITORY_UNAVAILABLE | 当前接口所需的数据暂时不可用。 |
校验详情码
收到 422 VALIDATION_ERROR 时，读取 error.details.code。此接口可能返回：
GRAPH_EXPANSION_FILE_ID_REQUIREDINVALID_GRAPH_EXPANSION_DEPTHINVALID_GRAPH_EXPANSION_FANOUT