网页搜索

AI Gateway 会代理受支持提供商的原生网页搜索工具，使模型能够回答训练截止日期之后的事件相关问题。搜索在上游提供商上运行；AI Gateway 对其标准功能 — 日志记录、缓存、速率限制和护栏 — 应用于该请求。

如何启用网页搜索取决于提供商。激活方式可以是 tools 数组中的工具条目，也可以是请求正文上的顶层标志。下表指引您到正确的章节。

支持的提供商

提供商	端点	激活方式
Anthropic	`POST /ai/v1/messages`	`tools: [{ "type": "web_search_20250305", "name": "web_search", "max_uses": N }]`
OpenAI	`POST /ai/v1/responses`	`tools: [{ "type": "web_search_preview" }]`
xAI	`POST /ai/v1/responses`	`tools: [{ "type": "web_search" }]`
Alibaba	`POST /ai/v1/chat/completions`	top-level `"enable_search": true`

对于产品本身就是搜索的提供商 — Perplexity 和 Parallel — 请参阅以搜索为主的提供商。

Anthropic 网页搜索

Anthropic 模型通过其原生 web_search_20250305 工具 ↗ 暴露网页搜索。将其添加到 POST /ai/v1/messages 请求的 tools 数组中。

受支持的模型 — anthropic/claude-haiku-4.5、anthropic/claude-opus-4.5、anthropic/claude-opus-4.6、anthropic/claude-opus-4.7、anthropic/claude-opus-4.8、anthropic/claude-sonnet-4.5、anthropic/claude-sonnet-4.6。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/messages" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "anthropic/claude-haiku-4.5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "What were the top news stories about Cloudflare this week? Summarize in three bullets."
      }
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 3
      }
    ]
  }'

使用 AI 绑定从 Worker 发起的等效调用：

const resp = await env.AI.run(
	"anthropic/claude-haiku-4.5",
	{
		max_tokens: 4096,
		messages: [
			{
				role: "user",
				content:
					"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
			},
		],
		tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"anthropic/claude-haiku-4.5",
	{
		max_tokens: 4096,
		messages: [
			{
				role: "user",
				content:
					"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
			},
		],
		tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

搜索调用和结果会以 server_tool_use 和 web_search_tool_result 内容块出现在响应中。可配置参数包括 max_uses、allowed_domains、blocked_domains 和 user_location — 完整列表请参阅 Anthropic 的网页搜索工具文档 ↗。

OpenAI 网页搜索

OpenAI 模型通过 Responses API 上的 web_search_preview 工具 ↗ 暴露网页搜索。使用 POST /ai/v1/responses 端点，并将该工具添加到 tools 数组。

受支持的模型 — openai/gpt-4.1、openai/gpt-4.1-mini、openai/gpt-4o、openai/gpt-4o-mini、openai/gpt-5、openai/gpt-5-mini、openai/gpt-5-nano、openai/gpt-5.1、openai/gpt-5.4、openai/gpt-5.4-mini、openai/gpt-5.4-nano、openai/gpt-5.4-pro、openai/gpt-5.5、openai/gpt-5.5-pro、openai/o3、openai/o4-mini。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/responses" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4o-mini",
    "input": "What were the top news stories about Cloudflare this week? Summarize in three bullets.",
    "max_output_tokens": 4096,
    "tools": [
      { "type": "web_search_preview" }
    ]
  }'

使用 AI 绑定从 Worker 发起的等效调用：

const resp = await env.AI.run(
	"openai/gpt-4o-mini",
	{
		input:
			"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
		max_output_tokens: 4096,
		tools: [{ type: "web_search_preview" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"openai/gpt-4o-mini",
	{
		input:
			"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
		max_output_tokens: 4096,
		tools: [{ type: "web_search_preview" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

OpenAI 网页搜索仅在 Responses API 端点（POST /ai/v1/responses）上可用。/ai/v1/chat/completions 端点不接受 web_search_preview 工具。

Responses API 同时接受 { "type": "web_search_preview" } 和 { "type": "web_search" }。此处示例使用 web_search_preview。

xAI 网页搜索

xAI 的多智能体 Grok 模型通过 Responses API 上的 web_search 工具 ↗ 暴露网页搜索。在 POST /ai/v1/responses 请求的 tools 数组中添加 { "type": "web_search" }。

受支持的模型 — xai/grok-4.20-multi-agent-0309。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/responses" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "xai/grok-4.20-multi-agent-0309",
    "input": "What were the top news stories about Cloudflare this week? Summarize in three bullets.",
    "max_turns": 4,
    "tools": [
      { "type": "web_search" }
    ]
  }'

使用 AI 绑定从 Worker 发起的等效调用：

const resp = await env.AI.run(
	"xai/grok-4.20-multi-agent-0309",
	{
		input:
			"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
		max_turns: 4,
		tools: [{ type: "web_search" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"xai/grok-4.20-multi-agent-0309",
	{
		input:
			"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
		max_turns: 4,
		tools: [{ type: "web_search" }],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

xai/grok-4.20-multi-agent-0309 是唯一通过 AI Gateway 接受网页搜索的 xAI 模型。对于其他 Grok 模型，请参阅不支持网页搜索的模型。

Alibaba (Qwen) 网页搜索

Alibaba DashScope Qwen 模型通过 chat completions 请求上的顶层 enable_search ↗ 标志启用网页搜索。与 Anthropic、OpenAI 和 xAI 不同，没有 tools 条目 — 仅通过该标志激活网页搜索。

受支持的模型 — alibaba/qwen3-max、alibaba/qwen3.5-397b-a17b。

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "alibaba/qwen3-max",
    "enable_search": true,
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "What were the top news stories about Cloudflare this week? Summarize in three bullets."
      }
    ]
  }'

使用 AI 绑定从 Worker 发起的等效调用：

const resp = await env.AI.run(
	"alibaba/qwen3-max",
	{
		enable_search: true,
		max_tokens: 4096,
		messages: [
			{
				role: "user",
				content:
					"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
			},
		],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

const resp = await env.AI.run(
	"alibaba/qwen3-max",
	{
		enable_search: true,
		max_tokens: 4096,
		messages: [
			{
				role: "user",
				content:
					"What were the top news stories about Cloudflare this week? Summarize in three bullets.",
			},
		],
	},
	{
		gateway: {
			id: "default", // or use a specific gateway name
		},
	},
);

DashScope 不会将基于搜索的上下文作为单独的工具调用响应块返回。它会将获取的上下文折叠到提示中作为额外的输入 token — 在成功的基于搜索的响应中，预计 prompt_tokens 会显著增加。

以搜索为主的提供商

对于某些提供商，主要 API 是搜索端点，而不是带有网页搜索工具的聊天端点。AI Gateway 通过 gateway.ai.cloudflare.com 上现有的提供商代理端点暴露它们。

AI Gateway 不提供与提供商无关的网页搜索抽象。请使用以下模式直接调用提供商代理。

Perplexity

通过 Perplexity 提供商代理调用任意 Perplexity Sonar 模型 ↗。

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/perplexity-ai/chat/completions \
  --header "Authorization: Bearer $PERPLEXITY_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "sonar",
    "messages": [
      { "role": "user", "content": "What were the top news stories about Cloudflare this week?" }
    ]
  }'

Parallel

通过 Parallel 提供商代理调用 Parallel 的 Search API。完整请求架构请参阅 Parallel 的 Search API 文档 ↗。

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/parallel/v1beta/search \
  --header "x-api-key: $PARALLEL_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "objective": "Top news stories about Cloudflare this week.",
    "processor": "base",
    "max_results": 10
  }'

不支持网页搜索的模型

以下模型不通过 AI Gateway 接受网页搜索：

Google Gemini — 不通过统一的 web_search 工具提供，因为 Vertex 的 OpenAI 兼容表面不会将其转换为 Gemini 的原生 googleSearch 工具。要使用 Gemini grounding，请将原生 google_search 工具传递给提供商特定的 Vertex 端点。
Grok chat-completions 模型 — xai/grok-4.20-0309-non-reasoning、xai/grok-4.20-0309-reasoning 和 xai/grok-4.3 使用 chat-completions 端点，该端点不接受 web_search 工具。对于 Grok 网页搜索，请参阅 xAI 网页搜索。
DeepSeek deepseek-v4-flash、deepseek-v4-pro — 这些模型仅接受函数工具。
MiniMax m2.7、m3 — 这些模型仅接受 { "type": "function" } 工具。
OpenAI gpt-4.1-nano、o1-pro、o3-mini — 上游对这些模型上的 web_search_preview 返回 invalid_request_error。
OpenAI gpt-4o-search-preview、gpt-4o-mini-search-preview — 这些预览模型在上游已弃用。

定价与日志记录

网页搜索请求按上游提供商的网页搜索费率计费，并与模型调用的其余部分一起通过 Unified Billing 流转。AI Gateway 不收取单独的网页搜索费用。

网页搜索工具调用及其结果可在 AI Gateway 日志中与请求和响应的其余部分一起查看。

支持的提供商

Anthropic 网页搜索

OpenAI 网页搜索

xAI 网页搜索

Alibaba (Qwen) 网页搜索

以搜索为主的提供商

Perplexity

Parallel

不支持网页搜索的模型

定价与日志记录

相关资源