企业官网建设流程全解析

WeKnora 分块管理 API 实战指南：Chunk 的查询、编辑、删除与生成问题管理

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora

导读：分块（Chunk）是 WeKnora 知识库中存储与检索的基本单元——原始文档经过解析切分后，每一段可独立向量化、可被检索定位的文本片段都是一个 Chunk。本文以 docs/api/chunk.md 为核心，完整讲解 WeKnora 提供的 6 个分块管理 REST 接口（列表、更新、删除、按 ID 直达、删除生成问题），并结合 internal/handler/chunk.go、internal/router/routes_knowledge.go 等源码，深入说明参数语义、权限模型、分块类型过滤与底层实现原理，帮助你安全、高效地对知识库内容进行细粒度治理。

一、接口总览

分块管理 API 挂载在/api/v1/chunks前缀下，所有接口都需要身份认证（Bearer Token 或X-API-Key），具体如下：

在开始调用前，你需要先通过知识库管理流程拿到两个标识：

• knowledge_id：知识（单篇文档）的 ID，在 知识管理 API 的创建/列表响应中返回，格式为 UUID，如4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5；
• chunk ID：分块的 ID，同样为 UUID，可在分块列表接口中获取。

关于前缀：源码 client/chunk.go 中所有请求均拼接/api/v1/chunks/...，本文示例与 docs/api/chunk.md 一致使用http://localhost:8080，实际部署时请替换为你的服务地址。

二、GET/chunks/:knowledge_id- 获取知识的分块列表

2.1 参数说明

路径参数：

查询参数：

2.2 请求示例

curl --location 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5?page=1&page_size=1' \ --header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json'

2.3 响应示例

{ "data": [ { "id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7", "tenant_id": 1, "knowledge_id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", "knowledge_base_id": "kb-00000001", "tag_id": "", "content": "彗星xxxx", "chunk_index": 0, "is_enabled": true, "status": 2, "start_at": 0, "end_at": 964, "pre_chunk_id": "", "next_chunk_id": "", "chunk_type": "text", "parent_chunk_id": "", "relation_chunks": null, "indirect_relation_chunks": null, "metadata": null, "content_hash": "", "image_info": "", "created_at": "2025-08-12T11:52:36.168632+08:00", "updated_at": "2025-08-12T11:52:53.376871+08:00", "deleted_at": null } ], "page": 1, "page_size": 1, "success": true, "total": 5 }

响应体为分页结构：data是当前页的分块数组，total是该知识下的分块总数，page/page_size回显本次请求的分页参数。

2.4 字段语义与源码解读

对照数据模型 internal/types/chunk.go，各字段含义如下：

2.5 用chunk_type过滤不同类型的分块

列表接口在底层实现上比原文档描述的更丰富。在 internal/handler/chunk.go 中：

• 默认只返回text类型的文本分块；
• 调用方可通过重复的chunk_type查询参数覆盖默认值，例如?chunk_type=image_caption&chunk_type=image_ocr。

internal/types/chunk.go 定义了完整的 ChunkType 枚举：

2.6 分页边界

从 handler 的校验逻辑（internal/handler/chunk.go）可以看到实际的分页约束，这在编码调用时需要特别注意：

• page < 1时强制置为1；
• page_size < 1时置为10（与文档标注的默认值 20 不同，注意以服务端行为为准）；
• page_size > 100时截断为100。

同时，Go 客户端封装 client/chunk.go 提供了ListKnowledgeChunks(ctx, knowledgeID, page, pageSize, chunkTypes...)方法，可以直接以可变参数传入chunk_type过滤条件，适合在 Go 服务中集成调用。

三、PUT/chunks/:knowledge_id/:id- 更新分块

更新指定分块的内容和属性。所有字段均可选，未传则保留原值。

3.1 参数说明

路径参数：

请求体字段：

3.2 请求示例

curl --location --request PUT 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \ --header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json' \ --data '{ "content": "更新后的分块内容", "is_enabled": true }'

3.3 响应示例

{ "data": { "id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7", "content": "更新后的分块内容", "is_enabled": true, "...": "其他字段同 GET 响应" }, "success": true }

3.4 底层实现细节

• 指针语义保留原值：服务端请求结构体UpdateChunkRequest中Content、IsEnabled等字段均为指针类型（internal/handler/chunk.go），JSON 中不传该字段时指针为nil，服务层会跳过该字段的更新，从而实现"可选字段、未传保留"的语义。
• 归属校验：handler 会先按:knowledge_id和:id取回分块，并校验分块确实属于 URL 中的 knowledge（internal/handler/chunk.go），防止同租户内用"一个 knowledge_id + 另一个 knowledge 的 chunk"进行越权写入。
• 修订号与索引同步：更新最终落到服务层UpdateDocumentChunk（internal/types/interfaces/chunk.go），该方法带expected_revision修订检查并同步检索索引；接口契约文档虽未列出，但请求体支持expected_revision字段用于并发控制，冲突时服务端返回 409 Conflict（Chunk was modified by another user; refresh and retry）。更新成功后响应中还会附带知识当前的summary_status与description，方便前端刷新摘要状态。
• 相应的 Go 客户端方法为 client/chunk.go 的UpdateChunk(ctx, knowledgeID, chunkID, request)。

四、DELETE/chunks/:knowledge_id/:id- 删除单个分块

4.1 请求示例

路径参数与 PUT 相同。

curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \ --header 'X-API-Key: sk-xxxxx'

4.2 响应示例

{ "message": "Chunk deleted", "success": true }

删除同样走fetchChunkAndVerifyOwnership归属校验；数据层使用软删除（deleted_at），不会物理抹除记录。Go 客户端对应 client/chunk.go 的DeleteChunk(ctx, knowledgeID, chunkID)。

五、DELETE/chunks/:knowledge_id- 删除知识下的所有分块

5.1 参数说明

路径参数：

5.2 请求示例

curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ --header 'X-API-Key: sk-xxxxx'

5.3 响应示例

{ "message": "All chunks under knowledge deleted", "success": true }

该接口适合"重建知识内容"的场景：先整体清空某篇知识下的全部分块，再重新导入解析。注意它是不可逆的批量操作，调用前请确认 knowledge_id 正确。底层调用ChunkService.DeleteChunksByKnowledgeID（internal/types/interfaces/chunk.go），Go 客户端封装为 client/chunk.go 的DeleteChunksByKnowledgeID(ctx, knowledgeID)。

六、GET/chunks/by-id/:id- 根据 ID 直接获取分块

无需提供knowledge_id即可获取分块。常用于跨知识库的引用展示。

6.1 参数说明

6.2 请求示例

curl --location 'http://localhost:8080/api/v1/chunks/by-id/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \ --header 'X-API-Key: sk-xxxxx'

响应：同GET /chunks/:knowledge_id列表中的单条data结构。

6.3 实现说明

该接口在 internal/handler/chunk.go 中由GetChunkByIDOnly实现，允许不做租户过滤直接按 ID 取分块——因为路由层已经先完成了对父知识库读权限的校验（见第七节）。这一设计非常适合引用场景：例如前端在展示 Agent 回答中引用的分块时，只需持有 chunk ID 即可拉取内容，而不必再层层拼接 knowledge 信息。Go 客户端方法为 client/chunk.go 的GetChunkByIDOnly(ctx, chunkID)。

七、DELETE/chunks/by-id/:id/questions- 删除分块下的某个生成问题

删除指定分块关联的某条生成问题。WeKnora 支持为文档分块自动生成"可能被提问的问题"（用于增强召回），该接口用于清理这些生成问题中的某一条。

7.1 参数说明

路径参数：

请求体字段：

7.2 请求示例

curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/by-id/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7/questions' \ --header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json' \ --data '{ "question_id": "q-00000001" }'

7.3 响应示例

{ "message": "Question deleted successfully", "success": true }

注意：当前服务端实现实际返回的message为"Question deleted"（见 internal/handler/chunk.go），文档示例中的文案以接口契约为准，两者均表示删除成功。从服务层看，DeleteGeneratedQuestion会同步更新分块的 metadata 并移除对应的向量索引（internal/types/interfaces/chunk.go）。

八、权限模型：谁能读写哪些分块

分块接口的鉴权比表面上复杂，全部由路由中间件在 internal/router/routes_knowledge.go 中统一完成，handler 本身只关心业务逻辑。调用前建议先确认自己的账号或 API Key 具备相应角色：

• 读接口（列表、按 ID 直达、查询修订记录）：要求Viewer 及以上角色，且对父知识库有读取权限（自有 / 组织共享 / 通过共享 Agent 获得访问）；
• 写接口（更新、删除、删除生成问题等）：要求知识库创建者（KB Owner）或 Admin+，且对父知识库有写权限；
• Scoped API Key：读写内容分别要求retrieve/ingest能力，并受知识库白名单约束；
• 通过by-id路径访问时，中间件会先由 chunk ID 反查父知识库再做鉴权（KBAccessWriteFromChunkIDParam/KBAccessReadFromChunkIDParam）。

这一点在编写集成脚本时尤为重要：即使你手握 API Key，若它绑定的角色或白名单不满足上述条件，调用会得到 403。

九、Go 客户端快速上手

如果是在 Go 服务中集成，推荐直接使用仓库提供的官方客户端 client/chunk.go，避免手工拼接 URL 与解析响应：

client, _ := client.NewClient(...) // 按 client/README.md 初始化 // 1. 分页拉取某篇知识下的文本分块 chunks, total, err := client.ListKnowledgeChunks(ctx, knowledgeID, 1, 20) // 2. 同时获取图片 OCR 与描述分块 chunks, _, err = client.ListKnowledgeChunks(ctx, knowledgeID, 1, 20, "image_caption", "image_ocr") // 3. 只更新 content 与 is_enabled（其他字段保留） updated, err := client.UpdateChunk(ctx, knowledgeID, chunkID, &client.UpdateChunkRequest{ Content: "更新后的分块内容", IsEnabled: true, }) // 4. 按 chunk ID 直接取分块（跨知识库引用展示） chunk, err := client.GetChunkByIDOnly(ctx, chunkID) // 5. 删除单个 / 整篇知识的所有分块 err = client.DeleteChunk(ctx, knowledgeID, chunkID) err = client.DeleteChunksByKnowledgeID(ctx, knowledgeID)

对应的请求/响应结构体（Chunk、ChunkListResponse、UpdateChunkRequest）也定义在 client/chunk.go 中，字段与 REST 响应一一对应。

十、常见错误排查与最佳实践

• 401 / 403：优先检查X-API-Key是否正确、账号角色是否为 Viewer+（读）或 KB Owner / Admin+（写），以及 Scoped Key 的retrieve/ingest能力和知识库白名单是否覆盖目标知识库；
• 404 Chunk not found：确认knowledge_id与 chunk ID 的对应关系——尤其使用PUT/DELETE /chunks/:knowledge_id/:id时，两个 ID 必须属于同一篇知识，否则会被归属校验拒绝；
• 409 Conflict：更新或回滚时传入了过期/错误的expected_revision，说明分块已被他人修改，需刷新后重试；
• 分页上限：page_size超过 100 会被截断为 100，超过 20 的场景建议分页拉取而非一次性取全量；
• 默认只返回文本分块：需要图片 OCR、表格摘要等其他类型时，务必显式传chunk_type参数，否则结果集会"变少"；
• 先查后删：批量删除接口（DELETE /chunks/:knowledge_id）不可恢复，生产环境建议先调用列表接口备份 chunk ID 与内容。

十一、关联阅读

• docs/api/chunk.md：本文对应的原始 API 契约文档；
• docs/api/README.md：全部 API 文档目录；
• internal/handler/chunk.go：分块接口的 HTTP 处理器实现；
• internal/router/routes_knowledge.go：分块路由注册与 RBAC 中间件装配；
• internal/types/interfaces/chunk.go：ChunkService/ChunkRepository接口定义；
• internal/types/chunk.go：Chunk数据模型、ChunkType/ChunkStatus枚举；
• client/chunk.go：分块管理的 Go 官方客户端封装；
• docs/api/knowledge.md：知识管理 API（获取knowledge_id）。

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora