LiteLLM 联网搜索 yunxiyang/dsh-web-search-litellm

dsh-web-search-litellm

DSH web_search 提供方，通过 LiteLLM 代理使用 OpenAI Responses 协议。请求携带服务端 web_search 工具，由 DeepSeek Responses API 原生执行；带依据的答案以及模型实际打开的真实 URL 会返回给 harness 的 web 接缝（ctx.web）。

- 不使用 Anthropic 协议 —— 发送 POST {baseURL}/responses，而非 /messages。
- 无需新密钥 —— 复用你的聊天 Models 页面已存储的 LITELLM_API_KEY 凭据。
- 无第三方搜索服务 —— 搜索在 DeepSeek 官方服务端运行，通过你现有的 LiteLLM 路由计费。
- 可在设置 UI 中完全配置（web-search-litellm 部分）。

简介 / 快速上手（中文）

这是 DeepSeek Harness ctx.web 能力的联网搜索提供方：web_search 请求走 OpenAI Responses 协议发往你的 LiteLLM 代理，由 DeepSeek 官方 Responses API 在服务端原生执行搜索，返回带真实来源 URL 的答案。

- 不需要 Anthropic 协议，也不需要新的 API Key——直接复用聊天模型页已配置的 LITELLM_API_KEY。
- 不接任何第三方搜索服务；搜索在 DeepSeek 官方服务端完成，走你现有的 LiteLLM 计费路由。
- 安装：dsh plugin --profile add dsh-web-search-litellm，然后在 profile 的 cordis.patch.yml 里把 web 的 searchProvider 设为 litellm-responses（详见下方英文说明）。
- 常见症状：web_search 报 Authentication Fails, Your api key is invalid，且你的 DEEPSEEK_API_KEY 其实是 LiteLLM 代理 key——装这个插件并把 baseURL 指向代理即可。

何时使用 / When to use

当以下任一情况符合你的处境时，选择此提供方：

- web_search 失败并报 Authentication Fails, Your api key: XXXX is invalid —— 通常是因为 DEEPSEEK_API_KEY 存的是 LiteLLM 代理 key，而非 DeepSeek 平台 key。
- 所有公司流量都必须经过 LiteLLM（直连 api.deepseek.com 被封锁或禁止）。
- 你更偏好 OpenAI Responses 协议，而非 Anthropic 的 /messages 格式。
- 你希望不使用免费额度 / 第三方搜索服务（Tavily、Brave、Exa 等）—— 搜索保持在 DeepSeek 官方服务端。
- 你通过 LiteLLM 代理使用 openai/deepseek-v4-flash 或 openai/deepseek-v4-pro 作为主模型。

安装

dsh plugin --profile add dsh-web-search-litellm
or from a local checkout:
dsh plugin --profile add ./dsh-web-search-litellm

然后路由接缝（profile 的 cordis.patch.yml）：

- id: web
config:
searchProvider: litellm-responses

optional: disable the shipped Anthropic-format DeepSeek provider
- id: web-search-deepseek
disabled: true

重启 profile（桌面端：设置 → 桌面设置 → 重启，或退出后重新打开）。

配置

设置部分 web-search-litellm（harness 设置 UI）或 bundle 补丁配置：

配置 —— 派生，而非硬编码

每个 endpoint/model 字段都是可选的。未设置时，提供方会从 dsh 的活动模型配置（聊天所用的同一提供方）派生其值，因此它在任何机器上都能工作，无需硬编码代理 URL 或模型：

- baseURL ← 活动提供方的 baseURL（聊天的网关）。
- apiKeyEnv ← 当前活跃 provider 的 apiKeyEnv。
- model ← 当前活跃模型的 id。
- candidateModels ← 当前活跃 provider 的完整 models[] 列表，这样发现过程可以在该网关上让每个模型竞速，并锁定第一个真正运行 web_search 的模型。

只有想覆盖派生值时才在此设置字段（例如强制指定某个搜索模型）。

| key | 默认值 | 含义 |
| baseURL | 派生 → $LITELLM_SEARCH_BASE_URL → http://127.0.0.1:4000/v1 | LiteLLM 代理根地址；会追加 /responses |
| model | 派生（当前活跃模型） | 起始模型 id；首选 |
| candidateModels | 派生（当前活跃 provider 的 models[]） | 当当前活跃模型未能真正运行 web_search 时并行竞速的备选池；最快的搜索者胜出并被缓存 |
| apiKeyEnv | 派生 → LITELLM_API_KEY | 每次搜索时解析的凭据引用 |
| apiKey | — | 可选的明文字面密钥（secret 角色） |
| maxTokens | 4096 | 单次搜索请求的 max_output_tokens |
| timeoutMs | 60000 | 响应流的连接截止时间 + 空闲截止时间；每当有数据到达时重置，因此缓慢但活跃的搜索永远不会被切断（仅在真正停滞时触发 WEB_TIMEOUT） |

工作原理

1. 模型以查询字符串调用 web_search。
2. 此 provider 向 {baseURL}/responses 发送 POST 请求，携带 tools: [{"type": "web_search"}]、stream: true。
3. LiteLLM 代理转发该调用；DeepSeek 在服务端执行搜索并将结果馈送给模型。
4. provider 解析 SSE 流：最终的 output_text 成为结果 content，而每个 action 为 open_page 的 web_search_call 项都会将其 URL 贡献到 sources。

会话兼容性（为什么此插件不写入自定义会话事件）

此插件不追加任何自己的会话事件。harness 以 fail-closed 方式读取会话日志：任何超出该构建的 KNOWN_SESSION_EVENT_TYPES 目录的事件类型都会中止加载，除非事件信封携带 ignorable: true。第三方类型永远不可能出现在该目录中，而公开的 session.append API 无法设置 ignorable，因此此处若使用仅用于日志的自定义事件，会使较旧的 harness 构建拒绝打开此插件运行过的任何会话。搜索仍可通过标准的 web_search 工具调用/结果事件在会话中完全可见。

已知上游限制（并非配置问题）

- DeepSeek 的 Responses API 文档说明 include 不受支持，因此结构化结果项在服务端被消费；所以 sources 仅携带 url（无标题/摘要）。
- 每次搜索消耗一轮 DeepSeek 模型调用（官方机制）。

许可证

MIT