Веб-поиск

Доступ к актуальным данным из интернета

Инструмент aitunnel:web_search даёт любой подходящей модели доступ к информации из сети в реальном времени. Модель сама решает, когда искать, формулирует запрос, получает результаты и отвечает со ссылками на источники.

Работает для Chat Completions (/v1/chat/completions) и Responses API (/v1/responses). Добавьте инструмент в массив tools — как обычный function-tool, но с префиксом aitunnel:.

Как это работает

Вы передаёте в запросе tools: [{ "type": "aitunnel:web_search" }] (параметры необязательны).
По промпту пользователя модель решает, нужен ли поиск, и формирует поисковый запрос.
AITUNNEL выполняет поиск выбранным движком (по умолчанию auto: нативный поиск провайдера, если доступен, иначе Exa).
Результаты (URL, заголовки, фрагменты контента) возвращаются модели.
Модель синтезирует ответ. В одном запросе она может искать несколько раз.

aitunnel:web_search можно комбинировать с вашими function-tools в том же массиве tools.

Быстрый старт

TypeScriptPythoncURL

typescript

const response = await fetch('https://api.aitunnel.ru/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk-aitunnel-xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.2',
    messages: [
      {
        role: 'user',
        content: 'Какие главные анонсы в мире ИИ были на этой неделе?',
      },
    ],
    tools: [{ type: 'aitunnel:web_search' }],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

python

import requests

response = requests.post(
    'https://api.aitunnel.ru/v1/chat/completions',
    headers={
        'Authorization': 'Bearer sk-aitunnel-xxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-5.2',
        'messages': [
            {
                'role': 'user',
                'content': 'Какие главные анонсы в мире ИИ были на этой неделе?',
            }
        ],
        'tools': [{'type': 'aitunnel:web_search'}],
    },
)

data = response.json()
print(data['choices'][0]['message']['content'])

bash

curl https://api.aitunnel.ru/v1/chat/completions \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {
        "role": "user",
        "content": "Какие главные анонсы в мире ИИ были на этой неделе?"
      }
    ],
    "tools": [{"type": "aitunnel:web_search"}]
  }'

Важно

Для включения веб-поиска в массиве tools должен быть объект { "type": "aitunnel:web_search" }. Параметры (parameters) необязательны.

Конфигурация

Все поля в parameters необязательны. Без parameters поиск включается с настройками по умолчанию.

json

{
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "engine": "exa",
        "max_results": 5,
        "max_total_results": 20,
        "search_context_size": "medium",
        "allowed_domains": ["example.com"],
        "excluded_domains": ["reddit.com"]
      }
    }
  ]
}

Параметр	Тип	По умолчанию	Описание
`engine`	string	`auto`	Движок: `auto`, `native`, `exa`, `parallel`, `perplexity`
`max_results`	integer	`5`	Максимум результатов за один поиск (1–25; для Perplexity — 1–20). Применяется к Exa, Parallel и Perplexity; игнорируется при нативном поиске провайдера
`max_uses`	integer	—	Максимум поисков за один запрос. После лимита дальнейшие вызовы поиска возвращают ошибку модели вместо выполнения. При нативном поиске параметр пробрасывается только Anthropic (как `max_uses`); остальные нативные провайдеры его игнорируют
`max_total_results`	integer	—	Суммарный лимит результатов по всем поискам в одном запросе. Удобно для контроля стоимости и размера контекста
`search_context_size`	string	—	Объём контекста: `low`, `medium`, `high`. Для Exa задаёт фиксированный лимит символов на результат (5K / 15K / 30K); если не указан, Exa выбирает адаптивно (~2–4K). Для Parallel управляет суммарным числом символов по всем результатам (по умолчанию `medium`). Для Perplexity мапится на нативный `search_context_size`. Игнорируется при нативном поиске. Перекрывается `max_characters`, если заданы оба
`max_characters`	integer	—	Точный максимум символов контента на результат (1–100 000). Применяется к Exa, Parallel и Perplexity; игнорируется при нативном поиске. Если заданы и `max_characters`, и `search_context_size`, приоритет у `max_characters`
`user_location`	object	—	Приблизительная локация для гео-смещения результатов. Сейчас поддерживается только нативным поиском провайдера; для Exa, Parallel и Perplexity игнорируется
`allowed_domains`	string[]	—	Ограничить результаты этими доменами (см. фильтрацию доменов)
`excluded_domains`	string[]	—	Исключить результаты с этих доменов (см. фильтрацию доменов)

Локация пользователя

Передайте приблизительную локацию, чтобы сместить результаты географически:

json

{
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "user_location": {
          "type": "approximate",
          "city": "Москва",
          "region": "Москва",
          "country": "RU",
          "timezone": "Europe/Moscow"
        }
      }
    }
  ]
}

Все поля внутри user_location необязательны.

Выбор движка

auto (по умолчанию) — нативный поиск, если провайдер модели его поддерживает, иначе Exa
native — предпочитает встроенный поиск провайдера; если модель его не поддерживает, откатывается на Exa
exa — поиск Exa: комбинация keyword- и embeddings-поиска. Возвращает highlights — релевантные выдержки со страницы, а не просто обрезанный текст
parallel — поиск Parallel
perplexity — Search API Perplexity: ранжированные результаты с фильтрами доменов и контролем размера контекста

Возможности движков

Возможность	Exa	Parallel	Perplexity	Native
Фильтрация доменов	Да	Да*	Да*	Зависит от провайдера
Контроль размера контекста	Да (на результат)	Да (суммарно)	Да	Нет

* У Parallel и Perplexity allowed_domains и excluded_domains взаимоисключающие. У Perplexity при одновременной передаче обоих приоритет у allowed_domains.

Exa

По умолчанию Exa выбирает размер выдержки адаптивно — обычно ~2 000–4 000 символов на результат. Управление бюджетом:

search_context_size: low → 5 000, medium → 15 000, high → 30 000 символов на результат
max_characters: точное значение 1–100 000; при одновременной передаче с search_context_size побеждает max_characters

json

{
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "engine": "exa",
        "max_characters": 2000
      }
    }
  ]
}

Выдержки возвращаются модели и клиенту через аннотации url_citation. Фрагменты из разных частей одной страницы разделяются маркером [...]:

text

Первый фрагмент со страницы.
[...]
Второй фрагмент из другой части той же страницы.
[...]
Третий фрагмент.

Parallel

Поддерживает фильтрацию доменов и search_context_size (лимит применяется суммарно ко всем результатам).

Perplexity

Возвращает ранжированные результаты (title, URL, snippet) без LLM-синтеза на стороне поисковика. Поддерживает фильтрацию доменов, search_context_size и max_characters.

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

При engine: "auto" или "native" используется встроенный поиск провайдера, если модель его поддерживает. Нативный поиск есть у:

OpenAI — GPT-4.1 / Mini / Nano, GPT-5 и новее, o3, o3 Pro, o4-mini
Anthropic — Claude 3.5 Haiku, Claude 3.7 Sonnet, Claude 4 и новее (Opus / Sonnet)
Google — Gemini 3 Flash / Pro, Gemini 3.1 Flash / Lite, Gemini 3.5 Flash
xAI — Grok 4 и новее (веб-поиск и поиск по X)
Perplexity — все модели Perplexity (поиск — ядро их API)

Старые модели OpenAI

GPT-4o, GPT-4o Mini и GPT-4 Turbo не поддерживают нативный веб-поиск. При engine: "native" для них будет откат на Exa. Для того же поведения достаточно engine: "auto" или опустить поле.

Проверить поддержку веб-поиска у конкретной модели можно на странице модели. Для моделей без нативного поиска укажите exa, parallel или perplexity — либо оставьте auto.

Фильтрация доменов

Ограничьте или исключите домены в результатах:

json

{
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "allowed_domains": ["arxiv.org", "nature.com"],
        "excluded_domains": ["reddit.com"]
      }
    }
  ]
}

Движок	`allowed_domains`	`excluded_domains`	Примечание
Exa	Да	Да	Можно вместе
Parallel	Да	Да	Взаимоисключающие
Perplexity	Да	Да	Взаимоисключающие; при обоих приоритет у `allowed_domains`
Native (Anthropic)	Да	Да	Взаимоисключающие
Native (OpenAI)	Да	Нет	`excluded_domains` игнорируется
Native (Google)	Нет	Нет	Не поддерживается. При `engine: "auto"` и фильтрах — откат на Exa; при `engine: "native"` — ошибка 400
Native (xAI)	Да	Да	Взаимоисключающие

Ограничение числа результатов

Если модель ищет несколько раз за один запрос, max_total_results ограничивает суммарное число результатов:

json

{
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "max_results": 5,
        "max_total_results": 15
      }
    }
  ]
}

После достижения лимита следующие вызовы поиска возвращают модели сообщение о лимите вместо нового поиска. Это помогает контролировать стоимость и размер контекста.

Ограничение числа поисков

Жёсткий лимит числа поисков за запрос — max_uses:

json

{
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "max_uses": 3
      }
    }
  ]
}

После лимита дальнейшие поиски не выполняются. При нативном поиске значение пробрасывается только Anthropic; остальные нативные провайдеры его игнорируют.

Аннотации и цитаты

Результаты поиска стандартизированы AITUNNEL в соответствии со схемой аннотаций OpenAI Chat Completions:

json

{
  "message": {
    "role": "assistant",
    "content": "Вот последние новости, которые я нашёл: ...",
    "annotations": [
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://www.example.com/web-search-result",
          "title": "Заголовок результата",
          "content": "Фрагмент содержимого страницы",
          "start_index": 100,
          "end_index": 200
        }
      }
    ]
  }
}

url — источник
title — заголовок (если доступен)
content — выдержка со страницы (если доступна)
start_index / end_index — позиция цитаты в тексте ответа

Responses API

Тот же инструмент aitunnel:web_search работает в /v1/responses — передайте его в tools вместе с input:

TypeScriptPythoncURL

typescript

const response = await fetch('https://api.aitunnel.ru/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk-aitunnel-xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.2',
    input: 'Какая сейчас цена Bitcoin?',
    tools: [
      {
        type: 'aitunnel:web_search',
        parameters: { max_results: 3 },
      },
    ],
  }),
});

const data = await response.json();
console.log(data);

python

import requests

response = requests.post(
    'https://api.aitunnel.ru/v1/responses',
    headers={
        'Authorization': 'Bearer sk-aitunnel-xxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-5.2',
        'input': 'Какая сейчас цена Bitcoin?',
        'tools': [
            {
                'type': 'aitunnel:web_search',
                'parameters': {'max_results': 3},
            }
        ],
    },
)

data = response.json()
print(data)

bash

curl https://api.aitunnel.ru/v1/responses \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "input": "Какая сейчас цена Bitcoin?",
    "tools": [
      {
        "type": "aitunnel:web_search",
        "parameters": {"max_results": 3}
      }
    ]
  }'

Учёт использования

Число фактических поисков отражается в usage ответа:

json

{
  "usage": {
    "prompt_tokens": 105,
    "completion_tokens": 250,
    "total_tokens": 355,
    "server_tool_use": {
      "web_search_requests": 2
    }
  }
}

Поле web_search_requests — сколько раз модель реально вызвала поиск в этом запросе (0–N). Тарификация идёт за фактические вызовы, а не за сам факт передачи aitunnel:web_search в tools.

Цены

Стоимость веб-поиска добавляется к обычной оплате токенов за обработку результатов. Тарификация идёт за фактические вызовы поиска (модель может искать 0–N раз за один запрос).

Движок	Цена
Exa	₽1.00 за запрос поиска. Включает до 10 результатов, далее ₽0.20 за каждый дополнительный результат
Parallel	₽0.20 за запрос поиска. Включает до 10 результатов, далее ₽0.20 за каждый дополнительный результат
Perplexity	₽1.00 за запрос поиска
Native	По тарифу провайдера модели — смотрите страницу модели (поле стоимости веб-поиска)

Все цены указаны за один вызов поиска и не включают стоимость токенов модели на чтение и синтез результатов.

Примеры

Размер контекста

json

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "Какие последние достижения в квантовых вычислениях?"
    }
  ],
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "search_context_size": "high"
      }
    }
  ]
}

Фильтры и лимиты

json

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "Свежие статьи про LLM с arXiv"
    }
  ],
  "tools": [
    {
      "type": "aitunnel:web_search",
      "parameters": {
        "engine": "exa",
        "max_results": 5,
        "max_uses": 3,
        "allowed_domains": ["arxiv.org"],
        "excluded_domains": ["reddit.com"]
      }
    }
  ]
}

Вместе с function-tools

json

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "Найди свежие новости про Apple и сравни с нашей внутренней котировкой"
    }
  ],
  "tools": [
    { "type": "aitunnel:web_search", "parameters": { "max_results": 3 } },
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "Текущая цена акции по тикеру",
        "parameters": {
          "type": "object",
          "properties": {
            "ticker": { "type": "string" }
          },
          "required": ["ticker"]
        }
      }
    }
  ]
}

См. также

Вызов инструментов — пользовательские tools / functions
Responses API — эндпоинт /v1/responses
Каталог моделей — поддержка веб-поиска и цены

Веб-поиск ​

Как это работает ​

Быстрый старт ​

Конфигурация ​

Локация пользователя ​

Выбор движка ​

Возможности движков ​

Exa ​

Parallel ​

Perplexity ​

Нативный поиск провайдеров ​

Фильтрация доменов ​

Ограничение числа результатов ​

Ограничение числа поисков ​

Аннотации и цитаты ​

Responses API ​

Учёт использования ​

Цены ​

Примеры ​

Размер контекста ​

Фильтры и лимиты ​

Вместе с function-tools ​

См. также ​

Веб-поиск

Как это работает

Быстрый старт

Конфигурация

Локация пользователя

Выбор движка

Возможности движков

Exa

Parallel

Perplexity

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

Фильтрация доменов

Ограничение числа результатов

Ограничение числа поисков

Аннотации и цитаты

Responses API

Учёт использования

Цены

Примеры

Размер контекста

Фильтры и лимиты

Вместе с function-tools

См. также