Vestavěné webové vyhledávání

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

Odpověď je běžné chatové dokončení se dvěma doplňky. Odpověď odkazuje na výsledky vyhledávání čísly v hranatých závorkách, sources říká, co které číslo znamená, a annotations označují, kde se každý z nich cituje:

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

Zapnutí vyhledávání

Vyhledávání je pole požadavku, ve výchozím stavu vypnuté. Nic se nehledá, pokud to požadavek neposlal.

Na /v1/messages leží pole na nejvyšší úrovni těla, vedle model a messages:

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

Co požadavek s vyhledáváním dělá

• API hledá na webu podle poslední zprávy uživatele. Dřívější kola konverzace dávají vyhledávání kontext.
• Vyhledávání proběhne u každého požadavku, který pošle web_search: true. Model nevolí, zda bude hledat.
• Výsledky se modelu předloží jako číslované zdroje a model z nich napíše odpověď.
• Odpověď začíná, když je vyhledávání hotové. Streamovaný požadavek do té doby neposílá nic, ani hlavičky, ani události, proto počítejte s delším čekáním před prvním chunkem.

Co odpověď obsahuje

• Odpověď má obvyklý tvar svého endpointu. Odpověď je v choices[0].message.content (blok text na /v1/messages).
• Text může nést značky jako [1] a [2] za tvrzeními, která podporují. Každé číslo odpovídá jednomu z výsledků, které model četl.
• sources pojmenovává tyto výsledky: jeden záznam pro každý výsledek, který model dostal, s index, title a url. Značka [1] je záznam s index 1. Uvedeny jsou i výsledky, které odpověď necituje.
• Na /v1/chat/completions má zpráva také annotations ve tvaru OpenAI: jeden url_citation pro každý zdroj, který značka jmenuje, s url, title a start_index a end_index, tedy pozicí značky v content počítanou ve znacích (konec se nezahrnuje).
• Ve streamu přichází sources s posledním chunkem a na /v1/messages s událostí message_delta. Anotace přicházejí v jednom chunku těsně před posledním, jako delta.annotations.
• sources je přítomno jen tehdy, když vyhledávání tohoto požadavku něco našlo. Odpověď bez něj byla napsána bez výsledků vyhledávání.

Jak se vyhledávání počítají

Každý plán zahrnuje určitý počet vyhledávání za den:

• Požadavek, jehož vyhledávání něco našlo, spotřebuje jedno vyhledávání z denního limitu. Vyhledávání, které nic nenašlo, nespotřebuje žádné.
• Chat a API sdílejí limit účtu, kterému klíč patří.
• Počítání začíná znovu každý den v 00:00 UTC.
• Výsledky vyhledávání jsou vstupní tokeny požadavku a účtují se spolu se zbytkem promptu.

Porovnat plány

Když jsou denní vyhledávání vyčerpána

Požadavek, který pošle web_search: true po posledním vyhledávání dne, není odmítnut. Odpoví se na něj bez vyhledávání: status je 200 a odpověď nemá sources.

Vyhledávání jako vlastní nástroj

web_search: true je jediný přepínač vyhledávání popsaného zde. Funkce, kterou definujete v tools a pojmenujete web_search, je jeden z vašich vlastních nástrojů: model vrátí volání a váš kód provede vyhledávání a pošle výsledek zpět.

Typy nástrojů pro vyhledávání z jiných platforem, například web_search_20250305 na /v1/messages nebo {"type": "web_search"} na /v1/responses, zde vyhledávání nespustí.

Chyby

Vyhledávání na webu nepřidává žádný stavový kód ani typ chyby. Vyhledávání, které nic nenajde, nebo den bez zbývajících vyhledávání dá běžnou odpověď bez výsledků vyhledávání. Každá další chyba je stejná jako u požadavku bez vyhledávání. Zpracování chyb