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

# 深度搜索

> 通过 PipeLLM WebSearch 做带内容提取和重排序的深度网络搜索

PipeLLM 通过公共网关暴露 WebSearch。适合直接在应用、后端或 Agent 工作流里获取网络
搜索结果，而不需要安装 npm 插件。

## Endpoint

| 方法    | 端点                                           |
| ----- | -------------------------------------------- |
| `GET` | `https://api.pipellm.ai/v1/websearch/search` |

## 认证

```text theme={null}
Authorization: Bearer $PIPELLM_API_KEY
```

## 查询参数

| 参数  | 类型     | 必填 | 描述    |
| --- | ------ | -- | ----- |
| `q` | string | 是  | 搜索关键词 |

## 这条路由会做什么

`/v1/websearch/search` 是完整检索链路。它会先拿搜索结果，再抽取页面内容，随后做向量
相似度检索和重排序，并在有内容可用时返回上下文。

## 请求示例

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api.pipellm.ai/v1/websearch/search?q=最新AI新闻" \
      -H "Authorization: Bearer $PIPELLM_API_KEY"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    response = requests.get(
        "https://api.pipellm.ai/v1/websearch/search",
        params={"q": "最新 AI 新闻"},
        headers={"Authorization": f"Bearer {os.getenv('PIPELLM_API_KEY')}"},
    )

    data = response.json()
    for result in data.get("data", {}).get("organic", []):
        print(f"- {result['title']}: {result['link']}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.pipellm.ai/v1/websearch/search?q=最新AI新闻",
      {
        headers: {
          Authorization: `Bearer ${process.env.PIPELLM_API_KEY}`,
        },
      }
    );

    const data = await response.json();
    data.data.organic.forEach((result) => {
      console.log(`- ${result.title}: ${result.link}`);
    });
    ```
  </Tab>
</Tabs>

## 响应格式

```json theme={null}
{
  "code": 200,
  "message": "ok",
  "took_ms": 6050,
  "data": {
    "organic": [
      {
        "title": "AI News | Latest News | Insights Powering AI-Driven Business ...",
        "link": "https://www.artificialintelligence-news.com/",
        "snippet": "AI News delivers the latest updates in artificial intelligence..."
      },
      {
        "title": "The Latest AI News and AI Breakthroughs that Matter Most",
        "link": "https://www.crescendo.ai/news/latest-ai-news-and-updates",
        "snippet": "Summary: Xiaomi has announced a next-gen AI voice model...",
        "contexts": [
          {
            "idx": 0,
            "text": "December 26, 2025\n\n# The Latest AI News and AI Breakthroughs..."
          }
        ]
      }
    ]
  }
}
```

## 响应字段

| 字段                               | 类型      | 描述         |
| -------------------------------- | ------- | ---------- |
| `code`                           | integer | `200` 表示成功 |
| `message`                        | string  | 状态信息       |
| `took_ms`                        | integer | 请求耗时（毫秒）   |
| `data.organic`                   | array   | 自然搜索结果     |
| `data.organic[].title`           | string  | 页面标题       |
| `data.organic[].link`            | string  | 页面 URL     |
| `data.organic[].snippet`         | string  | 搜索摘要       |
| `data.organic[].contexts`        | array   | 可选的页面上下文内容 |
| `data.organic[].contexts[].idx`  | integer | 上下文索引      |
| `data.organic[].contexts[].text` | string  | 提取出的文本内容   |

## 错误返回

```json theme={null}
{
  "code": 400,
  "message": "Bad Request, missing query parameter"
}
```

## 价格与限制

| 项目    | 值                                                      |
| ----- | ------------------------------------------------------ |
| 价格    | 每次成功深度搜索请求 \$0.08                                      |
| 内部模型名 | `websearch-deepsearch`                                 |
| 限流模型  | 共享账号级限额                                                |
| 重试行为  | 如果收到带 `Retry-After` 的 `503 Service Unavailable`，请等待后重试 |

PipeLLM 会根据这条路由自动写入 `websearch-deepsearch`，并把它保存在用量和请求审计记录中；
它不是客户端需要传入的参数。

## 示例：给 LLM 注入 RAG 上下文

```python theme={null}
import os
import requests
from openai import OpenAI

search_response = requests.get(
    "https://api.pipellm.ai/v1/websearch/search",
    params={"q": "OpenAI o3 模型能力"},
    headers={"Authorization": f"Bearer {os.getenv('PIPELLM_API_KEY')}"},
)
search_data = search_response.json()

context = "\n".join(
    f"[{r['title']}]({r['link']}): {r['snippet']}"
    for r in search_data.get("data", {}).get("organic", [])[:5]
)

client = OpenAI(
    api_key=os.getenv("PIPELLM_API_KEY"),
    base_url="https://api.pipellm.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": f"请基于以下上下文回答：\n{context}"},
        {"role": "user", "content": "OpenAI o3 有哪些主要特性？"},
    ],
)

print(response.choices[0].message.content)
```

## 相关文档

<Columns cols={3}>
  <Card title="WebSearch 总览" icon="globe" href="/websearch/overview.zh">
    产品总览、价格和接入入口
  </Card>

  <Card title="快速搜索" icon="bolt" href="/websearch/simple-search.zh">
    更快的搜索路由，不做深度检索
  </Card>

  <Card title="pipellm-websearch（npm）" icon="box" href="/websearch/npm-package.zh">
    从 npm 安装 OpenClaw 插件
  </Card>
</Columns>