Поиск в интернете

Два способа дать модели доступ к интернету: параметр web_search_options в теле запроса и серверный инструмент, передаваемый в tools[] без описания функции. Оба работают через /api/v1/chat/completions.

В примерах ниже $TEXT_MODEL — переменная окружения с идентификатором модели из GET /api/v1/models. Идентификаторы не зашивают в код: состав каталога меняется. Разбор — в разделе Модели и цены.

Поиск есть не у всех моделей. У модели без поддержки параметр молча игнорируется: запрос пройдёт, вернётся обычный ответ без поиска, ошибки не будет. Прежде чем полагаться на поиск, убедитесь на конкретной модели, что источники приходят.

`web_search_options`

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$TEXT_MODEL"'",
    "web_search_options": {
      "search_context_size": "medium",
      "user_location": {
        "type": "approximate",
        "city": "Москва",
        "country": "RU"
      }
    },
    "messages": [
      {"role": "user", "content": "Какие изменения в правилах уведомлений за последний месяц?"}
    ]
  }' | jq '{
    answer: .choices[0].message.content,
    annotations: .choices[0].message.annotations,
    cost: .usage.cost.total_cost
  }'

Поле	Тип	Смысл
`search_context_size`	string	Объём контекста, отдаваемого модели из найденного. Меньше — дешевле и быстрее, больше — полнее
`user_location`	object	Географический контекст: тип, страна, город, регион. Влияет на релевантность выдачи

user_location — подсказка, а не фильтр: поиск не ограничивается указанным регионом, но локальные запросы находятся лучше. Указывайте type явно, иначе часть полей может не примениться.

Python

import os

import requests

response = requests.post(
    "https://speshu.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['SPESHU_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": os.environ["TEXT_MODEL"],
        "web_search_options": {"search_context_size": "medium"},
        "messages": [
            {"role": "user", "content": "Какие изменения в правилах уведомлений за последний месяц?"}
        ],
    },
    timeout=300,
)
response.raise_for_status()

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

for note in message.get("annotations") or []:
    url = note.get("url_citation") or note.get("web_search") or {}
    if url.get("url"):
        print("-", url.get("title"), url["url"])

Серверный инструмент

Второй способ — передать в tools[] инструмент без объекта function. Это сигнал платформе, что инструмент исполняет она сама, а не ваш код:

{
  "tools": [
    { "type": "web_search" }
  ],
  "messages": [
    { "role": "user", "content": "Кто сейчас президент Франции?" }
  ]
}

Полный запрос:

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$TEXT_MODEL"'",
    "tools": [{"type": "web_search"}],
    "messages": [{"role": "user", "content": "Кто сейчас президент Франции?"}]
  }' | jq -r '.choices[0].message.content'

import os

import requests

response = requests.post(
    "https://speshu.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['SPESHU_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": os.environ["TEXT_MODEL"],
        "tools": [{"type": "web_search"}],
        "messages": [{"role": "user", "content": "Кто сейчас президент Франции?"}],
    },
    timeout=300,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

Разница с web_search_options в одном предложении: параметр включает поиск всегда, а инструмент — по решению модели; она может ответить из памяти, не потратив ни одного поиска.

Не смешивайте в tools[] серверные инструменты и ваши функции без необходимости: модели с разной поддержкой ведут себя по-разному, а tool_choice: "required" с серверным инструментом может не сработать. Держите два режима раздельно и переключайтесь явно.

Источники

Ссылки на найденное приходят в аннотациях ответа. Поле может отсутствовать, если поиск не выполнялся:

{
  "message": {
    "role": "assistant",
    "content": "По состоянию на сейчас президентом Франции является ... ",
    "annotations": [
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://example.org/news/president",
          "title": "Инаугурация нового президента",
          "start_index": 0,
          "end_index": 41
        }
      }
    ]
  }
}

Где	Поле
Чат, без потока	`message.annotations[]`
Responses API	события `output_text.annotation.added`
Поток чата	зависит от модели; рассчитывайте на отсутствие

Аннотации приходят не у всех моделей и не при каждом запросе. Показывайте пользователю источники только когда они реально есть в ответе, и никогда не подставляйте «источник» по умолчанию: отсутствие аннотации означает, что модель ответила из памяти, а не что ссылка потерялась.

Стоимость

Поиск увеличивает и входные токены (найденный текст идёт в контекст), и стоимость самого поиска. Ответ «без поиска» и ответ «с поиском» на одном и том же вопросе могут отличаться по цене в разы.

Не оценивайте стоимость поиска по формуле — читайте фактическое списание:

Python

usage = response["usage"]
print(usage["cost"]["total_cost"], "₽")
print(usage["prompt_tokens"], "входных токенов")

Тот же приём в потоке: usage приходит в предпоследнем кадре вместе со списанием. Полный разбор — в гайде по учёту средств, общие правила — в разделе Биллинг.

Практические замечания

Включайте поиск явно. В вопросе пишите, что нужна актуальная информация, и на всякий случай добавляйте web_search_options: без него модель ответит из памяти и выдаст устаревшее уверенным тоном. Проверяйте выдачу. Модель может сослаться на источник, которого в аннотациях нет, или перепутать факты. Если факт критичен, сверяйте по ссылкам из аннотаций. Задавайте search_context_size осознанно. Размер контекста прямо влияет на число входных токенов и на цену. Для «кто президент» хватит минимального, для разбора документации понадобится максимальный. Кэшируйте то, что стабильно. Поисковая выдача не кэшируется, а вот ваш системный промпт поверх неё — да, см. Кэширование.

Что дальше

Вызов функций

Ваши собственные инструменты в том же поле

Учёт средств

Как читать списание после поиска

Биллинг

Как считается стоимость запроса

Модели и цены

Возможности и ставки конкретных моделей

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

`web_search_options`

Серверный инструмент

Источники

Стоимость

Практические замечания

Что дальше

Вызов функций

Учёт средств

Биллинг

Модели и цены

​web_search_options

​Серверный инструмент

​Источники

​Стоимость

​Практические замечания

​Что дальше

Вызов функций

Учёт средств

Биллинг

Модели и цены

`web_search_options`

Серверный инструмент

Источники

Стоимость

Практические замечания

Что дальше