> Для получения чистого Markdown любой страницы добавьте .md к URL страницы. > Для полного индекса документации см. https://api.vega.chat/docs/llms.txt. > Для полного содержания документации см. https://api.vega.chat/docs/llms-full.txt. > Для интеграции AI‑клиента (Claude Code, Cursor и др.) подключитесь к MCP‑серверу по адресу https://api.vega.chat/docs/_mcp/server. # Веб‑поиск Инструменты сервера находятся в бета‑версии. API и поведение могут измениться. Инструмент сервера `openrouter:web_search` предоставляет любой модели на VEGA доступ к актуальной информации из интернета. Когда модель определяет, что ей нужна текущая информация, она вызывает инструмент с запросом поиска. VEGA выполняет поиск и возвращает результаты, которые модель использует для формирования обоснованного, с указанием источников ответа. ## Как это работает 1. Вы включаете `{ "type": "openrouter:web_search" }` в массив `tools`. 2. На основе подсказки пользователя модель решает, нужен ли веб‑поиск, и генерирует запрос поиска. 3. VEGA выполняет поиск, используя настроенный движок (по умолчанию `auto`, который использует нативный поиск провайдера, если он доступен, или переходит к [Exa](https://exa.ai)). 4. Результаты поиска (URL‑адреса, заголовки и фрагменты содержимого) возвращаются модели. 5. Модель синтезирует результаты в свой ответ. При необходимости она может выполнить несколько поисков в одном запросе. ## Быстрый старт ```typescript title="TypeScript" const response = await fetch('https://api.vega.chat/api/v1/chat/completions', { method: 'POST', headers: { Authorization: 'Bearer {{API_KEY_REF}}', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: '{{MODEL}}', messages: [ { role: 'user', content: 'What were the major AI announcements this week?' } ], tools: [ { type: 'openrouter:web_search' } ] }), }); const data = await response.json(); console.log(data.choices[0].message.content); ``` ```python title="Python" import requests response = requests.post( "https://api.vega.chat/api/v1/chat/completions", headers={ "Authorization": f"Bearer {{API_KEY_REF}}", "Content-Type": "application/json", }, json={ "model": "{{MODEL}}", "messages": [ { "role": "user", "content": "What were the major AI announcements this week?" } ], "tools": [ {"type": "openrouter:web_search"} ] } ) data = response.json() print(data["choices"][0]["message"]["content"]) ``` ```bash title="cURL" curl https://api.vega.chat/api/v1/chat/completions \ -H "Authorization: Bearer {{API_KEY_REF}}" \ -H "Content-Type: application/json" \ -d '{ "model": "{{MODEL}}", "messages": [ { "role": "user", "content": "What were the major AI announcements this week?" } ], "tools": [ {"type": "openrouter:web_search"} ] }' ``` ## Конфигурация Инструмент веб‑поиска принимает необязательные `parameters` для настройки поведения поиска: ```json { "type": "openrouter: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`, `firecrawl` или `parallel` | | `max_results` | integer | 5 | Максимальное количество результатов за один вызов поиска (1–25). Применяется к движкам Exa, Firecrawl и Parallel; игнорируется при нативном поиске провайдера | | `max_total_results` | integer | — | Максимальное общее количество результатов во всех вызовах поиска в одном запросе. Полезно для контроля стоимости и объёма контекста в агентных циклах | | `search_context_size` | string | — | Объём контекста, который нужно получить: `low`, `medium` или `high`. Для Exa задаёт фиксированный лимит символов на результат (5 К/15 К/30 К); если параметр опущен, Exa выбирает адаптивно (~2‑4 К на результат). Для Parallel управляет общим числом символов во всех результатах (по умолчанию `medium`). Игнорируется при нативном поиске и Firecrawl | | `user_location` | object | — | Приблизительное местоположение пользователя для географически ориентированных результатов. В данный момент поддерживается только нативным поиском; игнорируется в Exa, Firecrawl и Parallel (см. ниже) | | `allowed_domains` | string[] | — | Ограничить результаты указанными доменами. Поддерживается Exa, Firecrawl, Parallel и большинством нативных провайдеров (см. [фильтрацию доменов](#domain-filtering)) | | `excluded_domains` | string[] | — | Исключить результаты из указанных доменов. Поддерживается Exa, Firecrawl, Parallel и некоторыми нативными провайдерами (см. [фильтрацию доменов](#domain-filtering)) | ### Местоположение пользователя Передайте приблизительное местоположение, чтобы сместить результаты поиска в нужном направлении: ```json { "type": "openrouter:web_search", "parameters": { "user_location": { "type": "approximate", "city": "San Francisco", "region": "California", "country": "US", "timezone": "America/Los_Angeles" } } } ``` Все поля внутри `user_location` являются необязательными. ## Выбор движка Инструмент сервера веб‑поиска поддерживает несколько поисковых движков: * **`auto`** (по умолчанию): использует нативный поиск, если провайдер его поддерживает, иначе переходит к Exa * **`native`**: принудительно использует встроенный веб‑поиск провайдера (при отсутствии поддержки переходит к Exa с предупреждением) * **`exa`**: использует API поиска [Exa](https://exa.ai), который сочетает поиск по ключевым словам и векторный поиск. Возвращает [выделения Exa](https://docs.exa.ai/reference/contents-retrieval-with-exa-api#highlights) — отрывки из каждой страницы, наиболее релевантные запросу, а не усечённый текст страницы. См. раздел **Exa** ниже. * **`firecrawl`**: использует API поиска [Firecrawl](https://firecrawl.dev) (BYOK — bring your own key) * **`parallel`**: использует API поиска [Parallel](https://parallel.ai) ### Возможности движков | Возможность | Exa | Firecrawl | Parallel | Нативный | | ------------------------ | ------------ | ------------ | ------------ | ----------------- | | **Фильтрация доменов** | Да | Да | Да | Зависит от провайдера | | **Контроль объёма контекста** | Да* | Нет | Да** | Нет | | **API‑ключ** | На стороне сервера | BYOK (ваш ключ) | На стороне сервера | Обрабатывается провайдером | *\* Exa: ограничение применяется **на каждый результат** *\*\* Parallel: ограничение применяется как **общее количество** по всем результатам ### Exa VEGA запрашивает у Exa [выделения](https://docs.exa.ai/reference/contents-retrieval-with-exa-api#highlights) для каждого результата вместо опции `text`. Выделения — это извлечённые отрывки, выбранные Exa как наиболее релевантные запросу, что обычно даёт более качественный контекст на токен, чем усечённый текст страницы. По умолчанию Exa выбирает адаптивный размер выделения для каждого запроса и документа — обычно ~2 000–4 000 символов на результат. Чтобы задать фиксированный бюджет на результат, установите `search_context_size`, который сопоставляется с параметром Exa `contents.highlights.maxCharacters`: * `low` — 5 000 символов на результат * `medium` — 15 000 символов на результат * `high` — 30 000 символов на результат Если `search_context_size` опущен, VEGA позволяет Exa выбрать размер выделения адаптивно. Выделения возвращаются модели в каждом результате и отображаются вызывающим API через аннотации `url_citation`. Внутри одного результата отрывки из разных частей страницы разделяются маркерами Exa `[...]`, поэтому поле `content` аннотации `url_citation` может выглядеть так: ``` First excerpt drawn from the page. [...] Second excerpt drawn from elsewhere in the same page. [...] Third excerpt. ``` ### Firecrawl (BYOK) Firecrawl использует ваш собственный API‑ключ. Чтобы настроить: 1. Перейдите в [Настройки плагинов VEGA](https://api.vega.chat/settings/plugins) и выберите Firecrawl в качестве движка веб‑поиска. 2. Примите [Условия использования Firecrawl](https://www.firecrawl.dev/terms-of-service) — будет создан аккаунт Firecrawl, привязанный к вашему email. 3. Ваш аккаунт получает **10 000 бесплатных кредитов** (кредиты истекают через 3 месяца). Поиски Firecrawl используют ваши кредиты напрямую — дополнительных расходов от VEGA нет. Firecrawl поддерживает фильтрацию доменов (`allowed_domains` / `excluded_domains`), но они взаимно исключают друг друга — нельзя использовать оба параметра в одном запросе. ### Parallel [Parallel](https://parallel.ai) поддерживает фильтрацию доменов и контроль объёма контекста (`search_context_size`), а также использует кредиты VEGA по цене 0.5 ₽ за запрос. В запросе включено до 10 результатов, далее 0.1 ₽ за каждый дополнительный результат. ## Фильтрация доменов Ограничьте домены, которые могут появляться в результатах поиска, используя `allowed_domains` и `excluded_domains`: ```json { "type": "openrouter:web_search", "parameters": { "allowed_domains": ["arxiv.org", "nature.com"], "excluded_domains": ["reddit.com"] } } ``` | Движок | `allowed_domains` | `excluded_domains` | Примечания | | ----------------------- | :---------------: | :----------------: | --------------------------------------- | | **Exa** | Да | Да | Можно использовать одновременно | | **Parallel** | Да | Да | Взаимно исключают друг друга | | **Firecrawl** | Да | Да | Взаимно исключают друг друга | | **Native (Anthropic)** | Да | Да | Взаимно исключают друг друга | | **Native (OpenAI)** | Да | Нет | `excluded_domains` просто игнорируется | | **Native (xAI)** | Да | Да | Взаимно исключают друг друга | | **Native (Perplexity)** | Нет | Нет | Не поддерживается через путь инструмента сервера | ## Управление общим числом результатов Если модель выполняет несколько поисков в одном запросе, используйте `max_total_results`, чтобы ограничить суммарное количество результатов: ```json { "type": "openrouter:web_search", "parameters": { "max_results": 5, "max_total_results": 15 } } ``` После достижения лимита последующие вызовы поиска возвращают сообщение, информирующее модель о превышении лимита, вместо выполнения нового поиска. Это удобно для контроля стоимости и использования контекстного окна в агентных циклах. ## Работает с API Responses Инструмент сервера веб‑поиска также совместим с API Responses: ```typescript title="TypeScript" const response = await fetch('https://api.vega.chat/api/v1/responses', { method: 'POST', headers: { Authorization: 'Bearer {{API_KEY_REF}}', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: '{{MODEL}}', input: 'What is the current price of Bitcoin?', tools: [ { type: 'openrouter:web_search', parameters: { max_results: 3 } } ] }), }); const data = await response.json(); console.log(data); ``` ```python title="Python" import requests response = requests.post( "https://api.vega.chat/api/v1/responses", headers={ "Authorization": f"Bearer {{API_KEY_REF}}", "Content-Type": "application/json", }, json={ "model": "{{MODEL}}", "input": "What is the current price of Bitcoin?", "tools": [ {"type": "openrouter:web_search", "parameters": {"max_results": 3}} ] } ) data = response.json() print(data) ``` ## Отслеживание использования Использование веб‑поиска отражается в объекте `usage` ответа: ```json { "usage": { "input_tokens": 105, "output_tokens": 250, "server_tool_use": { "web_search_requests": 2 } } } ``` Поле `web_search_requests` считает общее количество запросов поиска, выполненных моделью в рамках данного запроса. ## Ценообразование | Движок | Ценообразование | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Exa** | 0.5 ₽ за запрос с использованием кредитов VEGA. Включает до 10 результатов, далее 0.1 ₽ за каждый дополнительный результат | | **Parallel**| 0.5 ₽ за запрос с использованием кредитов VEGA. Включает до 10 результатов в запросе, далее 0.1 ₽ за каждый дополнительный результат | | **Firecrawl**| Использует ваши кредиты Firecrawl напрямую — плата от VEGA не взимается | | **Native** | Передаётся от провайдера ([OpenAI](https://platform.openai.com/docs/pricing#built-in-tools), [Anthropic](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool#usage-and-pricing), [Perplexity](https://docs.perplexity.ai/getting-started/pricing), [xAI](https://docs.x.ai/docs/models#tool-invocation-costs)) | Все цены указаны дополнительно к стандартным затратам токенов LLM за обработку содержимого результатов поиска. ## Переход от плагина Web Search Плагин [web search](/docs/guides/features/plugins/web-search) (`plugins: [{ id: "web" }]`) и вариант `:online` (/docs/guides/routing/model-variants/online) устарели. Вместо них используйте серверный инструмент `openrouter:web_search`. Ключевые различия: | | Плагин Web Search (устарел) | Серверный инструмент Web Search | | ------------------------- | ---------------------------- | -------------------------------- | | **Как включить** | `plugins: [{ id: "web" }]` | `tools: [{ type: "openrouter:web_search" }]` | | **Кто решает выполнять поиск** | Всегда один поиск | Модель решает, когда и нужен ли поиск | | **Частота вызовов** | Один раз за запрос | 0 – N раз за запрос | | **Опции движка** | Native, Exa, Firecrawl, Parallel | Auto, Native, Exa, Firecrawl, Parallel | | **Фильтрация доменов** | Да (Exa, Parallel, некоторые нативные) | Да (Exa, Parallel, большинство нативных) | | **Контроль размера контекста** | Через `web_search_options` | Через параметр `search_context_size` | | **Ограничение общего числа результатов** | Нет | Да (`max_total_results`) | | **Ценообразование** | Зависит от движка | Зависит от движка (те же тарифы) | ### Пример миграции ```json // До (устарело) { "model": "openai/gpt-5.2", "messages": [...], "plugins": [{ "id": "web", "max_results": 3 }] } // После { "model": "openai/gpt-5.2", "messages": [...], "tools": [ { "type": "openrouter:web_search", "parameters": { "max_results": 3 } } ] } ``` ```json // До (устарело) — движок и фильтрация доменов { "model": "openai/gpt-5.2", "messages": [...], "plugins": [{ "id": "web", "engine": "exa", "max_results": 5, "include_domains": ["arxiv.org"] }] } // После { "model": "openai/gpt-5.2", "messages": [...], "tools": [{ "type": "openrouter:web_search", "parameters": { "engine": "exa", "max_results": 5, "allowed_domains": ["arxiv.org"] } }] } ``` ```json // До (устарело) — вариант :online { "model": "openai/gpt-5.2:online" } // После { "model": "openai/gpt-5.2", "tools": [{ "type": "openrouter:web_search" }] } ``` ## Следующие шаги * [Обзор серверных инструментов](/docs/guides/features/server-tools) — Узнайте о серверных инструментах * [Datetime](/docs/guides/features/server-tools/datetime) — Получите текущие дату и время * [Tool Calling](/docs/guides/features/tool-calling) — Узнайте о пользовательском вызове инструментов