Вградено уеб търсене

POST https://api.shannon-ai.com/v1/chat/completions

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "What is the weather forecast for Lisbon this weekend?"}],
    extra_body={"web_search": True},  # a Shannon field, so it goes in extra_body
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });

const response = await client.chat.completions.create({
  model: "shannon-3",
  messages: [{ role: "user", content: "What is the weather forecast for Lisbon this weekend?" }],
  web_search: true,
});

console.log(response.choices[0].message.content);

curl https://api.shannon-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "messages": [
      {"role": "user", "content": "What is the weather forecast for Lisbon this weekend?"}
    ],
    "web_search": true
  }'

Отговорът е обикновен chat completion с две добавки. Отговорът сочи към резултатите от търсенето с числа в квадратни скоби, sources казва какво означава всяко число, а annotations отбелязва къде е цитиран всеки от тях:

{
  "id": "chatcmpl-3e5a7c9b1d2f4a6c8e0b2d4f6a8c1e3b",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Saturday in Lisbon is forecast to be sunny with a high near 24 °C [1]. Sunday turns cloudy, with a chance of light rain in the afternoon [2].",
        "reasoning_content": null,
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 66,
              "end_index": 69,
              "url": "https://weather.example/lisbon/weekend",
              "title": "Lisbon weather: weekend outlook"
            }
          },
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 137,
              "end_index": 140,
              "url": "https://forecast.example/pt/lisbon/sunday",
              "title": "Sunday forecast for Lisbon"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2874,
    "completion_tokens": 41,
    "total_tokens": 2915
  },
  "sources": [
    {
      "index": 1,
      "title": "Lisbon weather: weekend outlook",
      "url": "https://weather.example/lisbon/weekend"
    },
    {
      "index": 2,
      "title": "Sunday forecast for Lisbon",
      "url": "https://forecast.example/pt/lisbon/sunday"
    },
    {
      "index": 3,
      "title": "Portugal: the week ahead",
      "url": "https://news.example/portugal/weather-week"
    }
  ]
}

Включване на търсенето

Търсенето е поле на заявката, по подразбиране изключено. Нищо не се търси, освен ако заявка не го изпрати.

На /v1/messages полето стои на най-горното ниво на тялото, до model и messages:

{
  "model": "shannon-3",
  "web_search": true,
  "messages": [
    {
      "role": "user",
      "content": "What is the weather forecast for Lisbon this weekend?"
    }
  ]
}

Какво прави заявка с търсене

• API търси в мрежата по последното съобщение на потребителя. По-ранните ходове на разговора дават контекст на търсенето.
• Търсенето се изпълнява при всяка заявка, която изпраща web_search: true. Моделът не избира дали да търси.
• Резултатите се поставят пред модела като номерирани източници и моделът пише отговора си от тях.
• Отговорът започва, когато търсенето е готово. Заявка със стрийминг не изпраща нищо, нито хедъри, нито събития, до този момент, така че предвидете по-дълго чакане преди първия фрагмент.

Какво съдържа отговорът

• Отговорът има обичайната форма на своя ендпоинт. Отговорът е в choices[0].message.content (блок text на /v1/messages).
• Текстът може да съдържа маркери като [1] и [2] след твърденията, които подкрепят. Всяко число съответства на един от резултатите, които моделът е прочел.
• sources назовава тези резултати: по един запис за всеки резултат, даден на модела, с index, title и url. Маркерът [1] е записът с index 1. Резултатите, които отговорът не цитира, също са изброени.
• На /v1/chat/completions съобщението има и annotations във формата на OpenAI: по един url_citation за всеки източник, назован от маркер, с url, title, start_index и end_index, тоест позицията на маркера в content, броена в символи (краят не се включва).
• В стрийм sources идва с последния фрагмент, а на /v1/messages със събитието message_delta. Анотациите идват в един фрагмент точно преди последния, като delta.annotations.
• sources има само когато търсенето на тази заявка е намерило нещо. Отговор без него е написан без резултати от търсене.

Как се броят търсенията

Всеки план включва определен брой търсения на ден:

• Заявка, чието търсене е намерило нещо, използва едно търсене от дневния лимит. Търсене, което не е намерило нищо, не използва никое.
• Чатът и API споделят лимита на акаунта, който притежава ключа.
• Броенето започва отново всеки ден в 00:00 UTC.
• Резултатите от търсенето са входни токени на заявката и се таксуват заедно с останалата част от prompt-а.

Сравнете плановете

Когато търсенията за деня са изчерпани

Заявка, която изпраща web_search: true след последното търсене за деня, не се отхвърля. Тя получава отговор без търсене: статусът е 200, а отговорът няма sources.

Търсене като Ваш собствен инструмент

web_search: true е единственият превключвател на описаното тук търсене. Функция, която дефинирате в tools и наименувате web_search, е един от Вашите собствени инструменти: моделът връща извикване, а Вашият код изпълнява търсенето и изпраща резултата обратно.

Типове инструменти за търсене на други платформи, като web_search_20250305 на /v1/messages или {"type": "web_search"} на /v1/responses, не стартират търсене тук.

Грешки

Уеб търсенето не добавя код за статус и тип грешка. Търсене, което не намира нищо, или ден без останали търсения дава нормален отговор без резултати от търсене. Всяка друга грешка е същата като за заявка без търсене. Обработка на грешки