Baike.dev
Log in
Back to tool/Back to issues
#3361·WeKnora

[Feature]: knowledge-search 普通文档标签过滤下推到向量索引，避免先展开 knowledge_ids

Author: songwenyongCreated Sep 17, 2026Updated Sep 17, 2026

Affected Component

Backend Service & API / Vector Database

Problem Description

希望 POST /api/v1/knowledge-search 在普通文档知识库中按标签搜索时，也能直接使用向量/检索索引的标签元数据过滤，避免每次先在关系数据库中展开全部文档 ID，再向检索后端传入 knowledge_id IN (...)。

已核对官方 main 提交 fa56b5b9。以下是源码核对结果，尚未进行性能基准测试。

当前普通文档路径：

knowledge-search 的 tag_ids
  → buildSearchTargets
  → 查询 knowledge_tag_relations，得到全部匹配的 knowledge_ids
  → HybridSearch(knowledge_ids=...)
  → 向量/关键词索引按 knowledge_id IN (...) 过滤

FAQ 路径则保留 TagIDs，直接交给检索后端过滤索引记录的 tag_id。

源码依据：

  1. 文档/FAQ 分支与 SearchTarget 构造：非 FAQ 调用 ListKnowledgeIDsByTagIDs，填充 KnowledgeIDs；原标签只保存在 ScopeTagIDs，没有填充物理索引过滤字段 TagIDs。FAQ 则保留 TagIDs。
  2. 关系表查询：连接 knowledge_tag_relations，按 tenant、KB、标签过滤，Distinct + Pluck 出文档 ID 列表。
  3. 检索参数传递：将目标中的 KnowledgeIDs / TagIDs 传给 HybridSearch。
  4. 腾讯向量数据库过滤器：已支持 knowledge_base_id、knowledge_id、tag_id 过滤。
  5. 现有单元测试也明确区分两种行为：文档标签解析为文档 ID、FAQ 保留索引标签过滤。本次仅阅读这些测试，未执行测试。

典型请求：

http
POST /api/v1/knowledge-search
Content-Type: application/json

{
  "query": "退款规则",
  "knowledge_base_id": "<document-kb-id>",
  "tag_ids": ["<tag-id>"]
}

当一个标签关联大量文档时，当前路径会先物化完整文档 ID 集合；额外的关系库查询、应用内 ID 列表及检索请求体大小均随匹配文档数增长。这是从实现推导出的扩展性问题，并非已测得的延迟或故障。

Proposed Solution

让普通文档的标签约束也下推到检索后端：在索引记录保存标签元数据，搜索时直接过滤这些标签，同时保留知识库范围、启用状态及显式文档范围约束。

期望链路：

knowledge-search 的 tag_ids
  → 已完成权限校验的 KB 范围 + 索引标签过滤条件
  → 向量/关键词检索后端直接过滤
  → rerank / merge / top-k

这需要同时完善索引数据，不能只替换查询分支：

  • 当前普通文档索引构造没有写入 TagID。需要在入库、重解析及相关索引重建路径中同步文档标签。
  • 普通文档已经支持多标签，不能仅复制一个标签到单值 tag_id 而丢失其他标签。可以使用后端支持的多值标签字段（如 tag_ids）或等价索引表示，保留现有“命中任意标签”的 OR 语义；兼容 FAQ 的现有单值 tag_id。
  • 文档标签新增、修改、移除、标签删除时，应同步检索索引元数据，并明确失败重试/一致性处理；不应仅为修改标签重新计算正文向量。
  • 历史索引需要回填/迁移；切换前保留旧路径作为兼容回退，避免已有知识库突然查不到结果。不支持相应元数据过滤的后端也可保留回退。
  • 向量召回与关键词召回应使用一致的标签范围；显式 knowledge_ids 与标签范围仍取交集。保留 tenant/共享访问授权和 KB 范围检查。
  • 补充多标签、标签修改/删除、旧索引迁移、显式文档交集以及不同检索后端的回归验证，并比较大标签集合下的请求大小和延迟。

Alternatives

保留当前关系表解析方案，并对文档 ID 集合做缓存或分批；但仍需处理标签变更后的缓存一致性及大 ID 集合传递。更希望在后端具备能力时直接使用索引标签过滤。

关系表仍可作为文档标签管理的事实来源；请求是减少搜索阶段的标签到全量文档 ID 展开，并非删除业务关系表。

Impact

My team or a small group

Use Case

通过知识搜索 API 在普通文档知识库内按业务标签检索，希望标签覆盖大量文档时，过滤条件的规模主要随标签数而非匹配文档数增长，同时与 FAQ/混合搜索的索引元数据过滤方式保持一致。

Additional Information

已检索相关 issue。#1783 讨论文档多标签能力，#2976 讨论 hybrid-search 的重排序能力；本请求针对普通文档标签过滤的执行位置及索引元数据同步。

Confirmation

  • I have searched existing issues and confirmed this is a new request
  • I understand this request may need discussion and evaluation

Source: Tencent/WeKnora

View original on GitHubView discussion on GitHub