> ## Documentation Index
> Fetch the complete documentation index at: https://platform.kimi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 联网搜索最佳实践

> 按场景选择搜索接口、控制成本、写有效查询词、配置参数，提升联网搜索结果质量。

Kimi 开放平台提供三个搜索与网页抓取接口：联网搜索 Basic、联网搜索 Pro 和网页抓取。本页介绍如何选对接口、控制成本、写出有效的查询词、配置参数，用更少的调用拿到更准的结果。

## 选择合适的接口

| 接口         | 端点                          | 返回内容                                         | 适合场景                 |
| ---------- | --------------------------- | -------------------------------------------- | -------------------- |
| 联网搜索 Basic | `POST /v1/tools/search`     | 相关网页的标题、链接和摘要；`include_content=true` 时附带网页正文 | 搜索结果展示、网页采集，或想自己加工正文 |
| 联网搜索 Pro   | `POST /v1/tools/search_pro` | 网页正文中与查询词最相关的内容片段，按相关性排序                     | 联网问答、RAG、Agent、报告与总结 |
| 网页抓取       | `POST /v1/tools/fetch`      | 指定网页的标题和 Markdown 正文                         | 已知目标 URL，需要获取网页正文    |

三个接口按次计费，价格见 [联网搜索价格](/docs/pricing/websearch)。

常见任务和推荐的接口：

| 你想完成的事情     | 推荐接口       | 说明                                          |
| ----------- | ---------- | ------------------------------------------- |
| 搜索结果展示      | 联网搜索 Basic | 网页标题、摘要、链接和正文适合作为来源卡片或结果列表直接展示              |
| 网页采集与自行加工   | 联网搜索 Basic | 拿到完整正文后接入自己的切块和筛选流程                         |
| 联网问答        | 联网搜索 Pro   | 返回与问题相关的内容片段，模型基于片段组织答案，并保留来源链接             |
| 实时 Web RAG  | 联网搜索 Pro   | 先搜索外部网页，再把相关片段作为临时检索结果交给模型                  |
| 报告与研究       | 联网搜索 Pro   | 围绕主题搜索多个来源，优先提取关键段落，再由模型整理为竞品分析、政策解读或行业报告   |
| 限定站点或时间范围搜索 | 联网搜索 Pro   | 通过 `sites` 和 `time_window` 参数约束搜索范围，提高结果相关性 |
| 已有明确网页地址    | 网页抓取       | 直接获取指定网页的标题和 Markdown 正文                    |

联网搜索 Pro 在 联网搜索 Basic 找到网页之后多做了一步：读懂正文，把与问题最相关的内容片段挑出来，按相关性排好序。

搜索结果最终要交给模型使用时，联网搜索 Pro 有三个好处：

* 回答更准：模型读到的是与问题最相关的片段，而不是夹杂导航和广告的整页原文，关键信息不被噪音稀释。
* 工程投入更少：正文切块和相关性排序已由服务端完成，不用自建和维护这套链路，拿到结果即可交给模型。
* 来源始终可溯：每个片段都保留所属网页的标题、链接和站点信息，答案可引用、可核查。

结果不经过模型、直接展示给用户时（搜索结果页、来源卡片），或者想自己加工正文（切块、筛选）时，联网搜索 Pro 的加工反而是多余的，建议选用 联网搜索 Basic。

## 控制成本

| 场景               | 做法                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| 只需要摘要判断相关性       | 联网搜索 Basic 保持 `include_content=false`（默认值），只返回标题、链接和摘要，最快、最便宜                                               |
| 需要细读正文           | 用 联网搜索 Pro，返回的正文片段（chunks）已按相关性排序，相比把整页原文交给模型，token 消耗通常能下降一个数量级（具体效果因查询和网页内容而异）。每个片段保留所属网页的标题、链接和站点信息，来源可溯 |
| 确定需要整页原文（例如全文入库） | 联网搜索 Basic 设置 `include_content=true`，或者对已知的 URL 直接调用网页抓取                                                    |

除了单次调用拿回的内容量，调用次数也影响成本。建议把同一信息需求的追问改写成一条更完整的查询词，合并成一次调用。近似查询词搜到的页面高度重叠，拆开调用就要为同一批页面重复付费；合并之后，同样的花费能覆盖更多不同的来源。

例如，想调研 2025 年诺贝尔物理学奖的获奖情况：

* ✗ 拆成三次调用：`2025 年诺贝尔物理学奖`、`2025 年诺贝尔物理学奖 获奖成果`、`2025 年诺贝尔物理学奖 实验验证`
* ✓ 合并成一次调用：`2025 年诺贝尔物理学奖 获奖成果 实验验证`

搜索与网页抓取调用的费用说明见 [联网搜索价格](/docs/pricing/websearch)。

如果单次搜索的结果不够深入，可以把查询词写得更具体。

## 写有效查询词

接口按提交的查询词（`text_query`）原样搜索，不会自动改写、补全或扩展。查询词决定搜到什么。模糊的查询词把调用浪费在无关页面上，具体的查询词让每个结果都有用。

把查询词写具体有三个维度：

| 维度  | 写法                                               | 反例               | 正例                    |
| --- | ------------------------------------------------ | ---------------- | --------------------- |
| 实体  | 给明确的专有名词（人名、公司、产品、事件名），不要给类别描述。没有实体，搜索引擎只能猜你要找什么 | `最近很火的 AI 大模型`   | `Kimi K3 新特性 评测`      |
| 时间  | 时效性问题带上年份、季度或版本号。时间词既影响结果的新鲜度，也帮助系统判断结果的相关性      | `最新财报`           | `2026 Q2 财报 营收`       |
| 限定词 | 限定角度或来源类型，决定搜到的是官网、新闻、公告原文还是论坛讨论                 | `Kimi K3 API 定价` | `Kimi K3 API 定价 官方文档` |

三个维度组合起来，一次调用就能拿到可以直接使用的材料：

* ✗ `诺贝尔奖`
* ✓ `2025 年诺贝尔物理学奖 获奖成果 实验验证`

另外还有两点要注意：

* **一次调用只表达一个信息需求**。把互不相关的问题堆进一条查询词，得到的只是一条又长又散的查询，结果质量反而下降。
* **不要用同义改写重发**。两次近似查询的结果高度重叠，等于为同一份结果付了两次费。第一次结果不好时，应该补实体、时间、限定词，或者换一个角度（换维度、换语言）。

## 按站点和时间过滤结果

联网搜索 Pro 提供两个约束参数，可以直接限定搜索范围：

* `sites`：限定来源站点，最多 5 个，多个站点按 OR 处理。例如 `["gov.cn", "miit.gov.cn"]` 让结果只来自指定站点。
* `time_window`：限定发布时间的起止范围，日期支持 `YYYY`、`YYYY-MM`、`YYYY-MM-DD` 三种格式。查询词里的时间词影响搜索和排序，`time_window` 直接按时间过滤结果，两者可以叠加。

## 设置结果数量和超时时间

联网搜索 Basic 和 联网搜索 Pro 还支持 `limit` 和 `timeout_seconds`，建议显式设置：

* `limit`：返回结果的数量上限，默认 5，范围 1 到 20。先取少量结果判断方向，再决定是否深入。
* `timeout_seconds`：超时时间，范围 1 到 60 秒。返回正文（`include_content=true`）或使用 联网搜索 Pro 时耗时更长，建议给足超时时间。

## 处理边界情况

* 网页能否取到正文，受网站可访问性、登录限制、反爬策略、页面结构和网络状况影响。搜索接口取不到正文时，仍会返回网页的标题、链接和摘要，可以先按摘要判断相关性，再决定是否换来源。
* 网页抓取 返回的 Markdown 是网页正文的提取结果，不包含图片、视频等多媒体资源。

## 完整示例

以下示例用 联网搜索 Pro 搜索 2025 年诺贝尔物理学奖：查询词包含时间和实体，`sites` 限定官方站点，`time_window` 限定发布时间范围：

```bash theme={null}
curl -X POST "https://api.moonshot.cn/v1/tools/search_pro" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text_query": "2025 年诺贝尔物理学奖 获奖成果 实验验证",
    "limit": 5,
    "timeout_seconds": 30,
    "sites": ["nobelprize.org"],
    "time_window": {
      "start": "2025-10",
      "end": "2025-12"
    }
  }'
```

响应中的每个结果包含网页的标题、链接、站点、日期和若干正文片段，片段按相关性排序，可以直接交给模型使用：

```json theme={null}
{
  "search_results": [
    {
      "title": "The Nobel Prize in Physics 2025 - Press release",
      "url": "https://www.nobelprize.org/prizes/physics/2025/press-release/",
      "site_name": "NobelPrize.org",
      "date": "2025-10-07",
      "snippet": "...",
      "chunks": [
        { "text": "……与查询词最相关的正文片段……", "score": 1.2432842 }
      ]
    }
  ]
}
```

其中 `chunks[].score` 是片段与查询词的相关性分数，只在同一次查询内有相对意义，不要跨查询比较绝对值。