会调用搜索，只是 Agent 搜索能力的第一步先。更难的是这方面，当结果不好时它能不能找到改进方向。并通过一轮轮实验把搜索变好？怎么说呢，

再看使用者痛点，搜索调优为何如此头疼

假设你刚上线一个商品搜索应用：搜品牌、品类和型号基本正常。但使用者输入“适合通勤的轻便双肩包”，结果就开始跑偏。

• 语义召回权重。长句理解变好，却可能削弱对精确型号词的匹配。
• 关键词匹配门槛。前几条结果更准，却导致零结果激增。
• 放大候选集，召回更多但噪声与延迟同步上升。

这些调优操作互相牵连：一次看似简单的改动往往同时影响召回、排序、零结果率和响应时延。要判断一套策略是否真的更好，需要准备 Query、批量搜索、相关性标注、离线评测还有 Bad Case 分析——一套繁琐且成本高昂的工作流。

过去。这套工作只能依赖搜索专家反复试验，既耗时又难以低成本、可复现地持续进行。老实说，

我们思考的观点是，既然 Agent 已经能够理解目标并调用搜索。它能否再向前一步——根据当前数据和 Query 分布自动提出候选策略，用实验验证收益，并解释“为什么这组配置更好”。

火山引擎在开源项目 SearchCLI 中提供了 vs search tune 命令。者只需提供应用、数据集和 Query Set，Agent 就可以完成：

• Query 校验与实验规划
• 候选策略生成
• 批量搜索 & 相关性标注
• 指标计算 & 结果对比
• 候选 Scene 创建

一、从“会搜索”到“会把搜索变好”

A I 搜索程序通常包含召回模式、关键词/语义权重、匹配门槛还有候选规模等配置。话说回来，参数越多，适配场景越强，但人工调优的门槛也随之升高。

主要难点不是单个参数怎么改，而是持续回答：

• 当前策略在哪些 Query 上表现不佳？
• 该增加关键词还是语义召回？
• 平均指标提高是否掩盖了某类 Query 的退化？
• 新策略是否会增加零结果或延迟？

搜索自迭代闭环：

Query 与业务数据 → 评测当前效果 → 生成候选策略 → 执行搜索与标注 →
比较指标和 Bad Case → 输出候选配置 → 人工确认后进入验证

"自"指流程由 Agent 持续驱动；"迭代"指每轮都有真实的 Query、标签和指标作为证据。生产变更仍保留明确的人为边界。

二、为什么是 Agent + Skills + CLI？

. 三层职责分离

• Agent：负责业务理解、判断是否需要合成 Query、制定实验计划，还有解释实验收益。话说回来，
• L​LM Skills：执行具体任务。如生成合成 Query、进行语义相关性判定。怎么说呢，
• C​LI：P​rocess‑level 的可靠执行器。保证长时间任务可复现、不丢失、中断可恢复。

A gent 会先判断使用者是否已有真实 Query；没有时才生成合成 Query 并交由使用者审阅。老实说，昂贵评测前必须先执行 plan。确认策略数、Query 数和最大标注量。最终落地时还要进行 dry‑run 并由使用者确认创建候选 Scene。

. 稳定执行的价值

A gent 若，CLI 正是确保这些操作不因意外而中断的关键。

三、一次自迭代如何发生

. 第一步先：准备高质量 Query Set

- 实际日志、客服问题或人工筛选的典型 Query 最具代表性。- 若缺乏真实数据，可从样本生成合成 Query。 但必须先展示样例及类型分布，让使用者确认其代表性。

. 接下来：校验 & 规划

• validate: 检查格式错误、重复 Query 与类型倾斜。并评估
• : 在不调用实际搜索或 LLM 的情况下预估策略数量、请求次数与最大标注量，让预算在正式投入前得到控制。

. 然后：运行 & 复核

C​LI 对每个候选执行批量搜索。先用 Source‑item 银标快速过滤，再用 LLM Judge 做语义相关性判断；随后计算 NDCG、MRR、Precision、零结果率和延迟等指标。报告不仅给出推荐策略，还保留每条 Query 的明细。以便 Agent 解读收益来源并检测潜在退化。

. 第四步：确认并创建候选 Scene

C​LI 输出结构化的 {runId。report,candidates};Agent 可以比较不同 Run，挑选最稳健的配置转化为候选 Scene。从整个过程对应来看，

query-generate → validate → plan → run → report → compare → apply

四、SPA —— 把预算花在值得评测的策略上

SPA是一套专为搜索调优设计的进化式实验分配框架。它解决了“评测成本高”“噪声大”“约束多”“结果必须可解释”的难题。

. Genome：带业务语义的参数基因组

{
"user_defined_recall_mode": "KeywordSemantic","dense_weight": ...。"text_weight": ...,"query_keyword_match_percent": ...,"max_retrieved_num": ...
}

- 参数既有枚举也有连续值，还存在归一化约束。- SPA 的交叉/变异在生成新基因前。会先进行合法性校验与归一化处理，确保每个基因都是可执行配置。

. 初始种群：覆盖真实行为而非随机撒点

• CURRENT Baseline 策略
• "KeywordOnly" / "SemanticOnly" 边界策略
• MATRIX Optimizer 粗粒度档位组合

Spa 从这些有意义的行为区域出发。而不是从完全随机点开始，明显提高早期探索效率。

. 多保真评测：层层过滤降低无效成本

. 多视角 Elite：保留多维度最佳解

Spa 同时保留这些方向，以免种群过早收敛到单一局部最优解。

. 演化与退火：探索 vs 利用平衡

Spa 使用温度控制探索幅度——早期温度高允许接受稍差但差异大的新基因；中期围绕 Elite 微调；后期温度降低，仅细调已证明价值区域，从而兼顾跳出局部最优和收敛稳定性。

. 鲁棒目标函数：防止“一次高分”误导决策

RobustScore = NDCG@k
+ α × MRR@k
- β × zero_result_rate
- γ × latency_penalty
- δ × query_type_variance
- ε × confidence_interval_width

NDCG 衡量整体排序质量；MRR 强调首位命中，零结果率 & 延迟是落地硬约束；query_type_variance 防止只在少数类型上好；confidence_interval_width 来自 Bootstrap 重抽样，用于惩罚不稳定的高分策略。

五、实验结果概览

• NDCG@10 提高 %～%
• NDCG@20 提高 %～%
• NNR@10 提高 %～% MRR@10 提高 %～%<\/ em>
Precision@10 提高 %~%<\/ em><\/ li> <\/ ul>

- 在服饰商品数据集上自动调优相较默认配置提高显著 - 在综合商品及图片内容数据集一样表现出两位数以上 NDCG 增益 - 效果提高受限于 Query 表征完整度与标签质量。在真实线上环境仍需进一步验证.

Plan – 编译实验成本 bash vs search tune plan \ --application-id \ --dataset-id \ --queries ./queries.jsonl\ --profile similarity-only\ --optimizer spa \ --json 该命令不调用实际检索或 LLM，只输出预计查询次数·策略数量·最大标注量，为预算控制提供第一手依据。

受控并发 – 将“大任务”拆成“小任务”。实现方式为 strategy × query 粒度任务队列 + 有界批次调度。每批使用 Promise.allSettled 汇总，单个失败不会导致整轮作废，也不会无限放大请求。

标签缓存 – LLM 判定属于可复用资产 缓存键 = {datasetId。queryHash,itemId,judgeConfig}。当任意维度变化时自动失效，避免误用历史标签。同时显著节省 LLM 调用费用。

Checkpoint / Resume – 中断后继续跑 CLI 持续写入 runId.json 包含已完成查询列表、已标注记录还有中间指标摘要。Agent 可使用相同 runId 恢复未完成部分，无需重新支付已完成的请求。

安全 Apply – 人工确认才生效 apply 阶段仅展示即将创建的 Scene 配置并要求手动确认；默认入口不会被自动切换，确保业务风险可控。话说回来，

1. 安装 Node.js并克隆仓库

   
   git clone :volcengine/SearchCLI.git
   cd SearchCLI
   ./scripts/install.sh
   

2. 注册 Skill 并登录

   
   npx skills add ":volcengine/SearchCLI.git" -y -g
   vs auth login
   vs doctor --json
   

3. 准备 queries.jsonl并执行完整闭环

vs search tune validate --queries ./queries.jsonl --json

vs search tune plan \ --application-id \ --dataset-id \ --queries ./queries.jsonl \ --profile similarity-only \ --optimizer spa \ --json

vs search tune report --run-id --json

vs search tune apply --run-id

 

E​lite 类型	E​valuation 指标/关注点
Global Best	Total NDCG / MRR 综合最高
Query‑Type Best	Specific query category 最佳
Stable Best	Low variance across bootstrap samples	No‑Zero‑Result Best	ZRR 最低且保持较好 NDCG	No‑Latency Best	P99 latency ≤ threshold	Diverse Candidate	Differences> delta from baseline	Slight uplift while keeping all constraints

---