Wbudowane wyszukiwanie w sieci

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

Odpowiedź to zwykłe uzupełnienie czatu z dwoma dodatkami. Odpowiedź wskazuje wyniki wyszukiwania liczbami w nawiasach kwadratowych, sources mówi, co oznacza każda liczba, a annotations zaznacza, gdzie każdy z nich jest cytowany:

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

Włączanie wyszukiwania

Wyszukiwanie to pole zapytania, domyślnie wyłączone. Nic nie jest wyszukiwane, dopóki zapytanie tego nie wyśle.

W /v1/messages pole leży na najwyższym poziomie treści, obok model i messages:

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

Co robi zapytanie z wyszukiwaniem

• API przeszukuje sieć pod kątem ostatniej wiadomości użytkownika. Wcześniejsze tury rozmowy dają wyszukiwaniu kontekst.
• Wyszukiwanie działa przy każdym zapytaniu, które wysyła web_search: true. Model nie wybiera, czy szukać.
• Wyniki są kładzione przed modelem jako ponumerowane źródła, a model pisze na ich podstawie odpowiedź.
• Odpowiedź zaczyna się, gdy wyszukiwanie jest gotowe. Zapytanie ze streamingiem nie wysyła do tego czasu niczego, ani nagłówków, ani zdarzeń, więc zaplanuj dłuższe oczekiwanie na pierwszy chunk.

Co zawiera odpowiedź

• Odpowiedź ma zwykły kształt swojego endpointu. Odpowiedź jest w choices[0].message.content (blok text w /v1/messages).
• Tekst może zawierać znaczniki takie jak [1] i [2] po twierdzeniach, które wspierają. Każda liczba oznacza jeden z wyników, które przeczytał model.
• sources wymienia te wyniki: jeden wpis dla każdego wyniku przekazanego modelowi, z index, title i url. Znacznik [1] to wpis z index 1. Na liście są też wyniki, których odpowiedź nie cytuje.
• W /v1/chat/completions wiadomość ma też annotations, w kształcie OpenAI: jedno url_citation dla każdego źródła, które wskazuje znacznik, z url, title oraz start_index i end_index, czyli pozycją znacznika w content liczoną w znakach (koniec nie jest wliczony).
• W streamie sources przychodzi z ostatnim chunkiem, a w /v1/messages ze zdarzeniem message_delta. Adnotacje przychodzą w jednym chunku tuż przed ostatnim, jako delta.annotations.
• sources jest tylko wtedy, gdy wyszukiwanie w tym zapytaniu coś znalazło. Odpowiedź bez tego pola została napisana bez wyników wyszukiwania.

Jak liczone są wyszukiwania

Każdy plan zawiera pewną liczbę wyszukiwań dziennie:

• Zapytanie, w którym wyszukiwanie coś znalazło, zużywa jedno wyszukiwanie z dziennego limitu. Wyszukiwanie, które nic nie znalazło, nie zużywa żadnego.
• Czat i API dzielą limit konta, do którego należy klucz.
• Licznik zaczyna od nowa co dzień o 00:00 UTC.
• Wyniki wyszukiwania są tokenami wejścia zapytania i są rozliczane razem z resztą promptu.

Porównaj plany

Gdy dzienne wyszukiwania się skończą

Zapytanie, które wysyła web_search: true po ostatnim wyszukiwaniu dnia, nie jest odrzucane. Dostaje odpowiedź bez wyszukiwania: status to 200, a odpowiedź nie ma sources.

Wyszukiwanie jako własne narzędzie

web_search: true to jedyny przełącznik opisanego tu wyszukiwania. Funkcja, którą zdefiniujesz w tools i nazwiesz web_search, jest jednym z Twoich własnych narzędzi: model zwraca wywołanie, a Twój kod wykonuje wyszukiwanie i odsyła wynik.

Typy narzędzi wyszukiwania z innych platform, takie jak web_search_20250305 w /v1/messages czy {"type": "web_search"} w /v1/responses, nie uruchamiają tu wyszukiwania.

Błędy

Wyszukiwanie w sieci nie dodaje kodu statusu ani typu błędu. Wyszukiwanie, które nic nie znajduje, albo dzień bez pozostałych wyszukiwań daje zwykłą odpowiedź bez wyników wyszukiwania. Każdy inny błąd jest taki sam jak dla zapytania bez wyszukiwania. Obsługa błędów