【No.10】feat(deepeyes): add pluggable text search backends

[WYXNICK]

What

Replace the DeepEyes-V2 text-search placeholder with deterministic offline mock, Search-R1 retriever, and configurable external HTTP backends.

Why

Implements Task 10: DeepEyes-V2 真实网页搜索工具.
Relates to #321. Registered participant: WYXNICK (Task 10 registration); this task does not require an RFC.

The example needs real retrieval when configured while retaining an offline default without search credentials.

How

• Use one YAML configuration entry point and an environment variable for the API key. Document a Tavily configuration without adding dependencies.
• Send the Search-R1 HTTP request format and normalize both raw and scored documents. All backends return elapsed_time and data with title, link, snippet, and nullable date.
• Bound retries for transient HTTP and transport failures. Invalid configuration or responses return the existing non-terminal "Error"; real-backend failures never silently fall back to mock.
• Forward search settings through both launchers with credential-sensitive shell tracing disabled. Keep parser, Agent loop, reward, and image-search behavior unchanged.

Testing

Validated on macOS with Python 3.12:

• pre-commit run --all-files passes
• Tests pass (pytest tests/) — full repository/GPU suite not run locally
• New tests added (if applicable)
• Documentation updated (if applicable)

python -m pytest tests/examples/deepeyes_v2_agentic -q --tb=short: 86 passed (upstream baseline: 12 passed).
Both launcher scripts pass bash -n; git diff --check passes.

Tests cover deterministic offline behavior, Search-R1 and external GET/POST protocols through a local HTTP server, result mapping, malformed configuration/responses, empty results, timeout/retry behavior, credential redaction, Agent continuation after success/failure, and launcher environment propagation.

No Search-R1-compatible deployment was available, and no live external API credentials were used. These are protocol/integration tests with a local HTTP server and scripted model responses, not live E5/FAISS or Tavily validation. GPU training and real Ray deployment were not run; the README includes a separate configured-service smoke test.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• CI/CD or build changes

Screenshots / Logs

86 passed in 4.35s
pre-commit: all 15 hooks passed

[rai-studio-bot]

Nyanpasu 审查看板

审查状态： ✅ 已通过

审查版本： e5e1df6

新目标提交 e5e1df6 为 main 的干净合并：PR 相对 main 的差异与此前已批准的 ba3977d 逐字节一致，main 侧改动不涉及示例文件及其依赖；合并后 86 项示例测试全部通过，启动脚本语法检查通过。未发现新问题，同意合入。验证边界：未使用真实 Search-R1 服务或外部 API 凭据，未运行多节点 GPU/Ray 训练。

审查阶段	进度	范围与结果
常规审查	✅ 已完成	确认 e5e1df6 为干净合并（PR 差异与已批准版本逐字节一致）；main 侧新增改动（megatron/CI/utils 等）不涉及 examples/deepeyes_v2_agentic 及其 relax 依赖导入；在合并后代码复跑 tests/examples/deepeyes_v2_agentic 86 项全部通过，bash -n 两个启动脚本通过。
深度审查	✅ 已完成	补齐此前看板缺失的生产与测试必要性审计：后端实现、启动脚本透传与三组测试均有真实调用方和独立失败模型支撑，全部保留；未发现可删除、合并或替换的冗余实现，无需独立设计子任务（diff 与已批准版本一致，无新增抽象）。

没有未解决的审查问题。

提交范围 · 接收 10 · 建议移出 0 · 待确认 0

接收 10 个文件 · 建议移出 0 个文件 · 待确认 0 个文件。移出与待确认部分暂停深审，不代表审查通过。

文件	结论	仓库维护必要性	依据	替代去向或方案
examples/deepeyes_v2_agentic/app/search_backends.py examples/deepeyes_v2_agentic/app/search_utils.py examples/deepeyes_v2_agentic/app/env_deepeyes_v2.py	接收	搜索后端实现与工具注册是本示例 Agent 循环的运行时行为：env_deepeyes_v2.py 注册的 web_search 工具经 search_utils 分发到 search_backends 的 mock/Search-R1/HTTP 实现，Task 10 要求可配置真实检索且保留离线默认。职责与前两轮已批准内容完全一致（本轮 diff 与 ba3977d 相对各自 merge-base 逐字节一致）。	Task 10 需求（redai-studio/community official-task.md#task-10，PR 描述引用）；现有调用方 examples/deepeyes_v2_agentic/app/env_deepeyes_v2.py 的工具注册与 Agent 循环。	仅保留 mock 或把实现放在 PR 证据产物中都无法交付配置后的真实检索；不新增依赖的 HTTP 后端已是最小机制。
examples/deepeyes_v2_agentic/README.md examples/deepeyes_v2_agentic/env.sh.example examples/deepeyes_v2_agentic/run_deepeyes_v2_agentic.sh examples/deepeyes_v2_agentic/run_deepeyes_v2_agentic_klx.sh	接收	启动脚本需把搜索配置与环境变量（API key）透传到 Ray 作业，env.sh.example 提供无凭据模板，README 记录 Tavily/Search-R1 配置与冒烟方法；这些是示例用户工作流的一部分。职责与前两轮一致。	Task 10 需求（一个 YAML 配置入口 + 环境变量传 key）；现有启动脚本的既有配置透传模式。	仅在外部文档描述配置而不改启动脚本，用户无法实际启用真实检索；独立文档站无法承载示例专属凭据透传。
tests/examples/deepeyes_v2_agentic/test_env_extractors.py tests/examples/deepeyes_v2_agentic/test_search_backends.py tests/examples/deepeyes_v2_agentic/test_search_launchers.py	接收	针对真实入口（后端协议、归一化、重试/超时、凭据脱敏、Agent 循环续跑、启动脚本环境透传）的持久回归测试，CPU 本地可跑、无需凭据，是仓库应维护的防护。职责与前两轮一致。	Task 10 的验证要求与仓库 tests/examples/ 既有测试布局。	仅以 PR 证据形式保留验证无法在后续改动时回归；替代为单一冒烟测试会丢失协议/边界覆盖。

精简审查与验证依据

审查范围	进度	结论
生产代码	✅ 已完成	审计 search_backends.py、search_utils.py、env_deepeyes_v2.py 改动与两个启动脚本：实现均由 Agent search 工具真实调用链支撑；考虑过的替代方案（把 retriever 折叠进 external 映射、用 shell 拼接替代 python3 JSON 合并、抽公共启动器辅助脚本）均会丢失 Search-R1 特有归一化或引入凭据引用风险，全部保留。
测试	✅ 已完成	审计三个测试文件：分别覆盖后端协议与错误分类、启动脚本真实执行与环境透传、工具调用提取边界，各自对应独立失败模型，无重复维护，全部保留。

生产代码的必要性与替代方案

范围	必须保留的契约	更简单的方案	结论	依据与限制
examples/deepeyes_v2_agentic/app/search_backends.py 全部新增实现（mock/retriever/external 三后端、配置校验、有界重试、结果归一化）及 search_utils.py 的重写、env_deepeyes_v2.py 的 query 提取修改	run_search(query, size) 返回 {elapsed_time, data:[{title,link,snippet,date}]}、失败抛 SearchError；调用方为 search_utils.search，再由 env_deepeyes_v2.exec_tool 的 search 工具分支调用（Agent 循环真实入口），失败保持既有非终止 Error 哨兵。	把 retriever 折叠进 external 的通用映射：无法表达 Search-R1 特有行为（document/score 包装、title 回退到 contents 首行、link 缺省为空）；旧 search_utils 的随机 sleep 假重试循环已被更简单的委托替代（净删 28 行）。	保留	调用链与行为由 86 项测试覆盖（协议、17 组坏配置、重试/超时、凭据脱敏、Agent 续跑），本轮在合并后 head 复跑全部通过；校验助手函数均被多处复用且无未使用分支。局限：未对真实 Search-R1/外部 API 做端到端验证。
run_deepeyes_v2_agentic.sh 与 run_deepeyes_v2_agentic_klx.sh 的搜索环境透传块、set +x 守卫，以及 env.sh.example、README 的搜索配置文档	两个启动脚本把 DEEPEYES_V2_SEARCH_CONFIG / DEEPEYES_V2_SEARCH_API_KEY 合入 ray job 的 runtime_env，凭据不进入 xtrace 与日志；调用方为示例用户的启动流程。	用 shell 字符串拼接替代 python3 JSON 合并可省约 12 行，但对含引号/反斜杠的 key 存在引用错误风险；两脚本重复的透传块沿用仓库既有的双启动器结构，抽公共 sourced 脚本会引入新文件。	保留	test_search_launchers.py 以真实脚本端到端执行并断言 key 到达 worker 且不出现在 stdout/stderr/日志（测试 key 含引号与反斜杠）；klx 侧块位于既有 WANDB set +x 区域内（run_deepeyes_v2_agentic_klx.sh:320-368）。

测试的必要性与替代方案

范围	必须保留的契约	更简单的方案	结论	依据与限制
tests/examples/deepeyes_v2_agentic/test_search_backends.py（399 行，本地 HTTP 服务器 + 脚本化模型）	守护后端契约：mock 离线确定性、坏配置即失败且不发请求、Search-R1/external 协议归一化、可重试（408/429/5xx）与不可重试（401/403/302）错误分类、有界重试与退避时序、凭据与响应体脱敏、Agent 循环在搜索成功/失败后继续。	压缩为少数冒烟用例：会丢失错误分类与脱敏边界（NaN/inf timeout、bool 当 int、嵌套 tool_call 标签等），这些正是新增配置面后的主要回归风险。	保留	86 项在本轮 head 全部通过；参数化用例各自对应独立失败模型，未发现重复断言；以脚本化模型替代 OpenAI SDK（第二轮提交的隔离修复），无外部服务依赖。
tests/examples/deepeyes_v2_agentic/test_search_launchers.py（83 行）与 test_env_extractors.py 新增的嵌套 tool_call 用例	前者在临时目录中以替身 ray/find/python3 端到端执行真实启动脚本，断言搜索变量进入 runtime_env 且凭据不泄漏到输出与日志；后者守护 JSON 字符串值中嵌套 <tool_call> 标签的提取边界。	静态 grep 启动脚本无法证明变量确实进入 runtime_env，也无法验证 xtrace 卫生；删除嵌套标签用例会放开门首次匹配解析回归。	保留	两个 launcher 参数化用例与提取用例在本轮 head 通过；launcher 测试无集群操作，仅需本机 python3 与 bash。

^{Powered by Nyanpasu with glm-5.3[1m] xhigh, please check the suggestions carefully.}

[rai-studio-bot]

已审查目标提交，未发现需要修改的问题，同意合入。核对了三个搜索后端、结果归一化、错误恢复和启动脚本环境传递；相关 CPU 测试 86 passed，两个启动脚本语法及 diff 检查通过。

当前无 CI 检查记录；未使用真实检索服务或外部 API 凭据，且缺少多节点 GPU/Ray 环境，因此未验证真实服务与训练部署。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

[rai-studio-bot]

已复核新提交，未发现新的问题，同意合入。重复校验的移除保留了原有约束，启动脚本仍保护凭据输出；相关 CPU 测试再次通过（86 passed），启动脚本语法及 diff 检查通过。

CI 尚在运行；本地未验证真实搜索服务或多节点 GPU/Ray 训练。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

[WYXNICK]

@SigureMo 您好，Task No.10已经完成，辛苦有空Review下，感谢。

[rai-studio-bot]

复核结论：同意合入

已审查目标提交 e5e1df62（合并 main）。本轮核验：该提交为 main 的干净合并，PR 相对 main 的差异与此前已批准的 ba3977dc 版本逐字节一致；main 侧新增改动不涉及本示例文件或其依赖导入。在合并后的代码上复跑 tests/examples/deepeyes_v2_agentic，86 项全部通过；两个启动脚本 bash -n 语法检查通过。验证边界保持不变：未使用真实 Search-R1 服务或外部 API 凭据，未运行多节点 GPU/Ray 训练。

审查看板：#342 (comment)

^{Powered by Nyanpasu with glm-5.3[1m] xhigh, please check the suggestions carefully.}