拓冰网站定制 
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具体如下方法路径描述GET/chunks/:knowledge_id获取知识的分块列表PUT/chunks/:knowledge_id/:id更新分块DELETE/chunks/:knowledge_id/:id删除单个分块DELETE/chunks/:knowledge_id删除知识下的所有分块GET/chunks/by-id/:id根据分块 ID 直接获取分块DELETE/chunks/by-id/:id/questions删除分块下的某个生成问题在开始调用前你需要先通过知识库管理流程拿到两个标识knowledge_id知识单篇文档的 ID在 知识管理 API 的创建/列表响应中返回格式为 UUID如4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5chunk ID分块的 ID同样为 UUID可在分块列表接口中获取。关于前缀源码 client/chunk.go 中所有请求均拼接/api/v1/chunks/...本文示例与 docs/api/chunk.md 一致使用http://localhost:8080实际部署时请替换为你的服务地址。二、GET/chunks/:knowledge_id- 获取知识的分块列表2.1 参数说明路径参数字段类型说明knowledge_idstring知识 ID查询参数字段类型默认说明pageint1页码page_sizeint20每页条数2.2 请求示例curl --location http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5?page1page_size1 \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json2.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.16863208:00, updated_at: 2025-08-12T11:52:53.37687108:00, deleted_at: null } ], page: 1, page_size: 1, success: true, total: 5 }响应体为分页结构data是当前页的分块数组total是该知识下的分块总数page/page_size回显本次请求的分页参数。2.4 字段语义与源码解读对照数据模型 internal/types/chunk.go各字段含义如下字段含义id分块唯一标识UUID主键seq_id自增整数 ID供外部 API如 FAQ 条目使用tenant_id租户 ID用于多租户隔离knowledge_id/knowledge_base_id父知识 / 知识库 IDtag_id知识库内的分类标签FAQ 场景常用content分块实际文本内容chunk_index分块在原始文档中的序号is_enabled是否启用可临时停用某些分块status分块状态0 默认、1 已存储、2 已索引见 internal/types/chunk.gostart_at/end_at在原始文本中的起始 / 结束字符偏移pre_chunk_id/next_chunk_id前驱 / 后继分块用于重建文档顺序chunk_type分块类型详见下文 2.5parent_chunk_id父分块 ID图片分块与原始文本分块关联relation_chunks/indirect_relation_chunks知识图谱关系分块关联 IDmetadataChunk 级扩展信息如 FAQ 元数据content_hash内容哈希用于快速匹配主要用于 FAQimage_info关联图片信息JSON 字符串created_at/updated_at/deleted_at时间戳与软删除标记GORMDeletedAt删除支持恢复2.5 用chunk_type过滤不同类型的分块列表接口在底层实现上比原文档描述的更丰富。在 internal/handler/chunk.go 中默认只返回text类型的文本分块调用方可通过重复的chunk_type查询参数覆盖默认值例如?chunk_typeimage_captionchunk_typeimage_ocr。internal/types/chunk.go 定义了完整的 ChunkType 枚举值含义text普通文本分块parent_text父子分块策略中的父文本仅用于上下文不参与向量索引image_ocr图片 OCR 文本image_caption图片描述文本summary摘要entity/relationship知识图谱实体 / 关系faqFAQ 条目web_searchWeb 搜索结果table_summary/table_column表格摘要 / 列描述wiki_pageWiki 页面同步分块2.6 分页边界从 handler 的校验逻辑internal/handler/chunk.go可以看到实际的分页约束这在编码调用时需要特别注意page 1时强制置为1page_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 参数说明路径参数字段类型说明knowledge_idstring知识 IDidstring分块 ID请求体字段字段类型必填说明contentstring否分块内容chunk_indexint否分块在知识中的序号is_enabledboolean否是否启用start_atint否起始位置字符偏移end_atint否结束位置字符偏移image_infostring否图像分块的元信息JSON 字符串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.goJSON 中不传该字段时指针为nil服务层会跳过该字段的更新从而实现可选字段、未传保留的语义。归属校验handler 会先按:knowledge_id和:id取回分块并校验分块确实属于 URL 中的 knowledgeinternal/handler/chunk.go防止同租户内用一个 knowledge_id 另一个 knowledge 的 chunk进行越权写入。修订号与索引同步更新最终落到服务层UpdateDocumentChunkinternal/types/interfaces/chunk.go该方法带expected_revision修订检查并同步检索索引接口契约文档虽未列出但请求体支持expected_revision字段用于并发控制冲突时服务端返回 409 ConflictChunk 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-xxxxx4.2 响应示例{ message: Chunk deleted, success: true }删除同样走fetchChunkAndVerifyOwnership归属校验数据层使用软删除deleted_at不会物理抹除记录。Go 客户端对应 client/chunk.go 的DeleteChunk(ctx, knowledgeID, chunkID)。五、DELETE/chunks/:knowledge_id- 删除知识下的所有分块5.1 参数说明路径参数字段类型说明knowledge_idstring知识 ID5.2 请求示例curl --location --request DELETE http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5 \ --header X-API-Key: sk-xxxxx5.3 响应示例{ message: All chunks under knowledge deleted, success: true }该接口适合重建知识内容的场景先整体清空某篇知识下的全部分块再重新导入解析。注意它是不可逆的批量操作调用前请确认 knowledge_id 正确。底层调用ChunkService.DeleteChunksByKnowledgeIDinternal/types/interfaces/chunk.goGo 客户端封装为 client/chunk.go 的DeleteChunksByKnowledgeID(ctx, knowledgeID)。六、GET/chunks/by-id/:id- 根据 ID 直接获取分块无需提供knowledge_id即可获取分块。常用于跨知识库的引用展示。6.1 参数说明字段类型说明idstring分块 ID6.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 参数说明路径参数字段类型说明idstring分块 ID请求体字段字段类型必填说明question_idstring是问题 ID7.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.goChunkService/ChunkRepository接口定义internal/types/chunk.goChunk数据模型、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WeKnora 分块管理 API 实战指南：Chunk 的查询、编辑、删除与生成问题管理
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具体如下方法路径描述GET/chunks/:knowledge_id获取知识的分块列表PUT/chunks/:knowledge_id/:id更新分块DELETE/chunks/:knowledge_id/:id删除单个分块DELETE/chunks/:knowledge_id删除知识下的所有分块GET/chunks/by-id/:id根据分块 ID 直接获取分块DELETE/chunks/by-id/:id/questions删除分块下的某个生成问题在开始调用前你需要先通过知识库管理流程拿到两个标识knowledge_id知识单篇文档的 ID在 知识管理 API 的创建/列表响应中返回格式为 UUID如4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5chunk ID分块的 ID同样为 UUID可在分块列表接口中获取。关于前缀源码 client/chunk.go 中所有请求均拼接/api/v1/chunks/...本文示例与 docs/api/chunk.md 一致使用http://localhost:8080实际部署时请替换为你的服务地址。二、GET/chunks/:knowledge_id- 获取知识的分块列表2.1 参数说明路径参数字段类型说明knowledge_idstring知识 ID查询参数字段类型默认说明pageint1页码page_sizeint20每页条数2.2 请求示例curl --location http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5?page1page_size1 \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json2.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.16863208:00, updated_at: 2025-08-12T11:52:53.37687108:00, deleted_at: null } ], page: 1, page_size: 1, success: true, total: 5 }响应体为分页结构data是当前页的分块数组total是该知识下的分块总数page/page_size回显本次请求的分页参数。2.4 字段语义与源码解读对照数据模型 internal/types/chunk.go各字段含义如下字段含义id分块唯一标识UUID主键seq_id自增整数 ID供外部 API如 FAQ 条目使用tenant_id租户 ID用于多租户隔离knowledge_id/knowledge_base_id父知识 / 知识库 IDtag_id知识库内的分类标签FAQ 场景常用content分块实际文本内容chunk_index分块在原始文档中的序号is_enabled是否启用可临时停用某些分块status分块状态0 默认、1 已存储、2 已索引见 internal/types/chunk.gostart_at/end_at在原始文本中的起始 / 结束字符偏移pre_chunk_id/next_chunk_id前驱 / 后继分块用于重建文档顺序chunk_type分块类型详见下文 2.5parent_chunk_id父分块 ID图片分块与原始文本分块关联relation_chunks/indirect_relation_chunks知识图谱关系分块关联 IDmetadataChunk 级扩展信息如 FAQ 元数据content_hash内容哈希用于快速匹配主要用于 FAQimage_info关联图片信息JSON 字符串created_at/updated_at/deleted_at时间戳与软删除标记GORMDeletedAt删除支持恢复2.5 用chunk_type过滤不同类型的分块列表接口在底层实现上比原文档描述的更丰富。在 internal/handler/chunk.go 中默认只返回text类型的文本分块调用方可通过重复的chunk_type查询参数覆盖默认值例如?chunk_typeimage_captionchunk_typeimage_ocr。internal/types/chunk.go 定义了完整的 ChunkType 枚举值含义text普通文本分块parent_text父子分块策略中的父文本仅用于上下文不参与向量索引image_ocr图片 OCR 文本image_caption图片描述文本summary摘要entity/relationship知识图谱实体 / 关系faqFAQ 条目web_searchWeb 搜索结果table_summary/table_column表格摘要 / 列描述wiki_pageWiki 页面同步分块2.6 分页边界从 handler 的校验逻辑internal/handler/chunk.go可以看到实际的分页约束这在编码调用时需要特别注意page 1时强制置为1page_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 参数说明路径参数字段类型说明knowledge_idstring知识 IDidstring分块 ID请求体字段字段类型必填说明contentstring否分块内容chunk_indexint否分块在知识中的序号is_enabledboolean否是否启用start_atint否起始位置字符偏移end_atint否结束位置字符偏移image_infostring否图像分块的元信息JSON 字符串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.goJSON 中不传该字段时指针为nil服务层会跳过该字段的更新从而实现可选字段、未传保留的语义。归属校验handler 会先按:knowledge_id和:id取回分块并校验分块确实属于 URL 中的 knowledgeinternal/handler/chunk.go防止同租户内用一个 knowledge_id 另一个 knowledge 的 chunk进行越权写入。修订号与索引同步更新最终落到服务层UpdateDocumentChunkinternal/types/interfaces/chunk.go该方法带expected_revision修订检查并同步检索索引接口契约文档虽未列出但请求体支持expected_revision字段用于并发控制冲突时服务端返回 409 ConflictChunk 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-xxxxx4.2 响应示例{ message: Chunk deleted, success: true }删除同样走fetchChunkAndVerifyOwnership归属校验数据层使用软删除deleted_at不会物理抹除记录。Go 客户端对应 client/chunk.go 的DeleteChunk(ctx, knowledgeID, chunkID)。五、DELETE/chunks/:knowledge_id- 删除知识下的所有分块5.1 参数说明路径参数字段类型说明knowledge_idstring知识 ID5.2 请求示例curl --location --request DELETE http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5 \ --header X-API-Key: sk-xxxxx5.3 响应示例{ message: All chunks under knowledge deleted, success: true }该接口适合重建知识内容的场景先整体清空某篇知识下的全部分块再重新导入解析。注意它是不可逆的批量操作调用前请确认 knowledge_id 正确。底层调用ChunkService.DeleteChunksByKnowledgeIDinternal/types/interfaces/chunk.goGo 客户端封装为 client/chunk.go 的DeleteChunksByKnowledgeID(ctx, knowledgeID)。六、GET/chunks/by-id/:id- 根据 ID 直接获取分块无需提供knowledge_id即可获取分块。常用于跨知识库的引用展示。6.1 参数说明字段类型说明idstring分块 ID6.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 参数说明路径参数字段类型说明idstring分块 ID请求体字段字段类型必填说明question_idstring是问题 ID7.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.goChunkService/ChunkRepository接口定义internal/types/chunk.goChunk数据模型、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考