43 lines
3.3 KiB
Markdown
43 lines
3.3 KiB
Markdown
# @deepseek-ai/dsh-web-search-exa
|
||
|
||
[English](README.md) | 中文
|
||
|
||
由 [Exa](https://exa.ai) 支持的 `WebSearchProvider`，用于 harness [web 能力 seam](../web/README.md)（`ctx.web`）。它调用 Exa 的 `POST /search` 端点并请求 highlight 内容，把扁平 `results[]` 映射为 seam 规范化的 `WebSearchResult`。
|
||
|
||
这是一个**实现** 包：它向 `ctx.web` 注册提供方，不拥有 `ctx.web` key，也不注册面向模型的工具（后者属于 `@deepseek-ai/dsh-tool-web`）。与 `@deepseek-ai/dsh-llm-deepseek` 一样，它是函数／namespace 插件（`inject: ['web']`），负责注册后端，而非默认导出服务。
|
||
|
||
## 配置
|
||
|
||
| Key | 默认值 | 含义 |
|
||
|---|---|---|
|
||
| `apiKey` | `$EXA_API_KEY` | Exa API key。为空／缺失时提供方不可用。 |
|
||
| `baseURL` | `https://api.exa.ai` | 端点基址；追加 `/search`。无法解析时提供方不可用。 |
|
||
| `searchType` | `auto` | 以 Exa `type` 发送的检索模式：`auto`（由 Exa 决定）、`keyword` 或 `neural`。 |
|
||
| `numResults` | （未设置） | 请求不含 `maxResults` 时使用的默认结果数。未设置时不发送默认值。必须是正整数。 |
|
||
| `highlightsPerResult` | `1` | 每个结果请求的 highlight 句子数（Exa `highlightsPerUrl`）。必须是正整数。 |
|
||
|
||
```yaml
|
||
- id: web-search-exa
|
||
name: '@deepseek-ai/dsh-web-search-exa'
|
||
config:
|
||
apiKey: !!js process.env.EXA_API_KEY
|
||
```
|
||
|
||
## 映射
|
||
|
||
Exa 返回扁平 `results[]`，不返回生成答案，因此省略 `content`。每项结果映射为 `WebSearchSource`：`url` ← `url`、`title` ← `title`、`snippet` ← 第一个非空 `highlights[]` 配置项（没有 highlight 的结果缺少可移植 snippet，会被丢弃）、`publishedAt` ← `publishedDate`。请求的 `maxResults` 优先于已配置的默认 `numResults`，并作为 Exa `numResults` 发送，以优化成本／延迟；最终边界由 seam 强制执行。提供方失败（HTTP 错误、网络失败、无法解析或形状错误的主体）以 `WebError` `WEB_PROVIDER_ERROR` 呈现；中止请求以 `WEB_ABORTED` 呈现。HTTP 重定向会在接触 `Location` 目标前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。
|
||
|
||
## 模型体验
|
||
|
||
通过 [`dsh-tool-web`](../tool-web/README.md) 间接影响；该工具保留此提供方经 `maxResults` 限制的 URL、标题、首条 highlight 与发布日期，或将精确的 `Exa search aborted`、`Exa search request failed: <error>` 和 `Exa returned an unprocessable response body: <error>` 失败置于消费方错误包装内；生成答案与提供方私有字段不进入上下文。
|
||
|
||
#### KV Cache 影响
|
||
|
||
不会直接失效；请求前缀变更由命名消费方负责。
|
||
|
||
## 已知限制与暂缓事项
|
||
|
||
- **没有非空 highlight 的结果会被整个丢弃**：没有可映射的可移植 snippet，因此返回源可能少于请求数量。
|
||
- **只公开 `searchType`／`numResults`／`highlightsPerResult`**：Exa 的其他控制项（livecrawl、category、domain/date filter、全文内容）等待提供方无关 seam 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
|
||
- **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。
|