摘要：本文是 VeapAI 企业 AI 知识库实战系列的第七篇，聚焦 Milvus 调试搜索环节。文章通过检索模板与检索审计两张表，把 TopK、阈值、过滤表达式等检索参数固定为可调、可查的契约，让向量检索从"黑盒"变成"留痕"的透明过程。内容涵盖表设计、页面操作、源码走读、调参习惯与复现步骤，帮助读者把检索调参从玄学变成有据可查的工程实践。
# 从零打通企业 AI 知识库全链路：VeapAI 实战（七）Milvus 调试搜索
> 关键词：Milvus 检索、向量检索调参、TopK 阈值 | 首发：CSDN | 同步：知乎 / 掘金
![本系列 8 步流程总览（当前：⑦ Milvus 调试搜索）]
## 检索是个黑盒，直到你让它留痕
向量写进去了，问答上线前还有个环节：验证检索本身行不行。TopK 取多少、阈值卡多少、过滤表达式写得对不对，全靠猜的话，问答效果就是玄学。
VeapAI 的解法是两件事：检索模板把参数固定下来，检索审计把每次调用记下来。前者让你调参，后者让你知道每次调的效果。
## 表设计
`ai_vector_search_template`（检索模板）：
| 字段 | 说明 |
| ---- | ---- |
| `template_code` | 租户内唯一 |
| `collection_id` | 目标集合 |
| `top_k` | 默认 10 |
| `score_threshold` | 分数阈值，decimal(10,6)，可选 |
| `filter_expr` | Milvus 过滤表达式，varchar(1000) |
| `output_fields` | 输出字段列表（JSON） |
| `search_params` | 检索参数（JSON），rerank 配置单列 `rerank_config` |
| `status` | 0 停用 1 启用 |
模板这张表实际上是检索的"参数契约"：TopK、阈值、过滤表达式、输出字段、检索参数都收口在这里，其中 rerank 配置单列 `rerank_config`。重排是检索质量的重要一截，配置单列意味着它是检索流程里的正式环节，而不是塞在某个 JSON 角落里的附带项。契约集中，扩展就集中——加新的检索参数，扩模板字段，不用散改问答代码。
`ai_vector_search_audit`（审计）：
| 字段 | 说明 |
| ---- | ---- |
| `query_text` | 查询文本（来自调试台） |
| `query_vector_hash` | 向量 hash。**不落向量本体** |
| `top_k` / `filter_expr` / `search_params` | 本次检索的参数快照 |
| `result_count` / `latency_ms` | 结果数与耗时 |
| `status` / `error_msg` | success / fail 与错误信息 |
| `operator_ip` | 操作 IP |
索引 `idx_search_audit_collection(tenant_id, collection_id, created_time)`，按集合翻检索历史。审计表存 hash 不存向量，这个细节很关键：向量本体几百 KB 一条，落库既费空间又没必要，hash 足够对账。审计记录是为了"这次检索发生了什么"，不是存档检索内容本身——知道自己要什么，是这类表设计的分寸。
![核心表关系 ER 图（简化版，只标关键属性与核心联动）]
## 页面操作
![检索模板]
「Milvus 管理 → 检索模板」建模板：选集合、定 TopK、填阈值、写过滤表达式（比如 `region_code == "440000"`）。
![调试搜索]
调试台输入查询文本直接搜，返回片段带分数；每次调试都写一条审计记录。调完一组参数，去审计页翻历史，哪次检索空结果、哪次延迟高，一眼能看出来。
第 3 篇提到应用知识配置里的 `min_score`，它和这里的 `score_threshold` 是两个层面的参数：前者是应用对知识主题的召回门槛，后者是模板层面的检索参数。调参顺序建议先在调试台把模板参数调到位，再把应用侧的召回门槛对齐。
## 源码走读
`com.veap.milvus.controller.AiVectorSearchTemplateController`、`AiVectorSearchAuditController`，服务实现在 `com.veap.milvus.service.impl.AiVectorSearchTemplateServiceImpl`。检索的底层走 `milvusops` 包的 facade，同第 2 篇的 collection 操作一样经过统一断言和审计。
## 一个提效的小习惯
`filter_expr` 是 Milvus 原生表达式语法，写错不会报 SQL 错，而是安静地返回空结果。调试时先不填 filter 确认向量召回正常，再加 filter，一次只变一个变量。这个顺序能让"为什么没结果"少一半。
顺带说，模板 + 审计的组合还解决了一个团队协作问题：检索参数是谁调的、调成了什么值，审计表里每次都有快照。接手的人不用问"上次效果好的那组参数是多少"，翻审计记录就行。调参从玄学变成有据可查，靠的就是这两张表。
## 复现
用第 6 篇向量化后的集合建一个模板：TopK 从 5 起步，阈值先不设。在调试台搜一条确定存在的知识点原文，观察分数区间；再把阈值设到区间中位数，确认过滤生效。审计页确认每次调试都有记录。
下一篇收尾：政策问答。知识搜索、知识溯源、文档在线定位预览，这条链路在问答页里怎么串起来。
项目地址：https://gitee.com/mindock/veap
