Веб-поиск

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

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

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

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

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

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

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"}]
  }'

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

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

{
  "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"]
      }
    }
  ]
}

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

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

{
  "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: ранжированные результаты с фильтрами доменов и контролем размера контекста

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

* У 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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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 работает в /responses — передайте его в tools вместе с input:

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 ответа:

{
  "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 раз за один запрос).

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

Примеры

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

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

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

{
  "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

{
  "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
• Серверные инструменты — обзор инструментов, которые исполняет AITUNNEL
• Каталог моделей — поддержка веб-поиска и цены