← Cloudflare AI Gateway / ai-gateway / usage

Web Search

AI Gateway проксирует встроенные инструменты веб-поиска поддерживаемых провайдеров, чтобы модели могли отвечать на вопросы о событиях, произошедших после даты завершения обучения. Поиск выполняется на стороне провайдера верхнего уровня; при этом AI Gateway применяет к запросу свои стандартные функции: логирование, кэширование, ограничение скорости запросов и Guardrails.

Способ включения веб-поиска зависит от провайдера. Активация выполняется либо через запись инструмента на 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`	верхнего уровня `"enable_search": true`

Для провайдеров, чей продукт представляет собой сам поиск (Perplexity и Parallel), см. Провайдеры, ориентированные на поиск.

Веб-поиск Anthropic

Модели Anthropic предоставляют веб-поиск через собственный web_search_20250305 инструмент ↗. Добавьте его в tools массив в POST /ai/v1/messages запрос.

Поддерживаемые модели, 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
      }
    ]
  }'

Аналогичный вызов из Worker с использованием привязки AI:

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 предоставляют веб-поиск через web_search_preview инструмент ↗ в Responses API. Используйте 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" }
    ]
  }'

Аналогичный вызов из Worker с использованием привязки AI:

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 инструмент.

Оба { "type": "web_search_preview" } и { "type": "web_search" } принимаются в Responses API. В примерах здесь используется web_search_preview.

веб-поиск xAI

Мультиагентная модель Grok от xAI предоставляет веб-поиск через web_search инструмент ↗ в Responses API. Добавьте { "type": "web_search" } к tools массив в POST /ai/v1/responses запрос.

Поддерживаемые модели, 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" }
    ]
  }'

Аналогичный вызов из Worker с использованием привязки AI:

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 единственная модель xAI, которая поддерживает веб-поиск через AI Gateway. Для остальных моделей Grok см. Модели без поддержки веб-поиска.

Веб-поиск Alibaba (Qwen)

Модели Alibaba DashScope Qwen поддерживают веб-поиск через параметр верхнего уровня enable_search ↗ флаг в запросе chat completions. В отличие от Anthropic, OpenAI и xAI, здесь нет tools записи: web search включается только этим флагом.

Поддерживаемые модели, 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."
      }
    ]
  }'

Аналогичный вызов из Worker с использованием привязки AI:

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 не возвращает контекст, найденный через поиск, в виде отдельных блоков ответов вызова инструментов, а встраивает его в промпт как дополнительные входные токены: ожидайте prompt_tokens значительно увеличиться при успешном ответе, основанном на результатах поиска.

Провайдеры, ориентированные на поиск

У некоторых провайдеров основной API представляет собой эндпойнт поиска, а не эндпойнт чата с инструментом веб-поиска. AI Gateway предоставляет доступ к ним через существующие прокси-эндпойнты провайдера по адресу gateway.ai.cloudflare.com.

AI Gateway не предоставляет абстракцию веб-поиска, независимую от провайдера. Обращайтесь к прокси провайдера напрямую, используя приведённые ниже шаблоны.

Perplexity

Вызывайте любой модель Perplexity Sonar ↗ через прокси провайдера Perplexity.

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

Вызывайте Search API от Parallel через прокси провайдера Parallel. См. в документации 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 инструмент, поскольку OpenAI-совместимый интерфейс Vertex не преобразует его в собственный для 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, вышестоящий сервер возвращает invalid_request_error для web_search_preview на этих моделях.
OpenAI gpt-4o-search-preview, gpt-4o-mini-search-preview, эти предварительные модели устарели на стороне поставщика.

Цены и логирование

Запросы веб-поиска оплачиваются по тарифам провайдера на веб-поиск и проходят через Unified Billing вместе с остальной частью вызова модели. AI Gateway не взимает отдельную плату за веб-поиск.

Вызовы инструмента веб-поиска и их результаты видны в AI Gateway журналы вместе с остальной частью запроса и ответа.

REST API, четыре конечные точки, на которые нацелены эти примеры
Workers Bindings, env.AI.run справочник
Поставщик Anthropic
провайдер OpenAI
провайдер Grok (xAI)
провайдер Perplexity
провайдер Parallel
Unified Billing

Web Search

Поддерживаемые провайдеры

Веб-поиск Anthropic

веб-поиск OpenAI

веб-поиск xAI

Веб-поиск Alibaba (Qwen)

Провайдеры, ориентированные на поиск

Perplexity

Parallel

Модели без поддержки веб-поиска

Цены и логирование

Дополнительные материалы