Ugrađena web pretraga

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

Odgovor je običan chat completion s dva dodatka. Odgovor upućuje na rezultate pretrage brojevima u uglatim zagradama, sources kaže što svaki broj označava, a annotations označava gdje se na svaki od njih poziva:

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

Uključivanje pretrage

Pretraga je polje zahtjeva, zadano isključeno. Ništa se ne pretražuje osim ako ga zahtjev pošalje.

Na /v1/messages polje stoji na najvišoj razini tijela, pokraj model i messages:

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

Što radi zahtjev s pretragom

• API pretražuje web za zadnju korisničku poruku. Raniji okreti razgovora daju pretrazi kontekst.
• Pretraga se provodi na svaki zahtjev koji šalje web_search: true. Model ne bira hoće li pretraživati.
• Rezultati se stavljaju pred model kao numerirani izvori, a model iz njih piše svoj odgovor.
• Odgovor počinje kada je pretraga gotova. Zahtjev sa streamingom do tada ne šalje ništa, ni zaglavlja ni događaje, zato računajte na dulje čekanje prije prvog chunka.

Što odgovor sadrži

• Odgovor ima uobičajeni oblik svog endpointa. Odgovor je u choices[0].message.content (blok text na /v1/messages).
• Tekst može nositi oznake poput [1] i [2] iza tvrdnji koje podupiru. Svaki broj označava jedan od rezultata koje je model pročitao.
• sources imenuje te rezultate: jedan unos za svaki rezultat koji je model dobio, s index, title i url. Oznaka [1] je unos s index 1. Navedeni su i rezultati na koje se odgovor ne poziva.
• Na /v1/chat/completions poruka ima i annotations, u OpenAI obliku: jedan url_citation za svaki izvor koji oznaka imenuje, s url, title te start_index i end_index, položajem oznake u content izbrojenim u znakovima (kraj nije uključen).
• U streamu sources dolazi s zadnjim chunkom, a na /v1/messages s događajem message_delta. Anotacije dolaze u jednom chunku neposredno prije zadnjeg, kao delta.annotations.
• sources postoji samo ako je pretraga ovog zahtjeva nešto pronašla. Odgovor bez njega napisan je bez rezultata pretrage.

Kako se pretrage broje

Svaki plan uključuje određeni broj pretraga dnevno:

• Zahtjev čija je pretraga nešto pronašla troši jednu pretragu iz dnevnog dopuštenog iznosa. Pretraga koja nije pronašla ništa ne troši nijednu.
• Chat i API dijele dopušteni iznos računa kojem ključ pripada.
• Brojanje počinje ponovno svaki dan u 00:00 UTC.
• Rezultati pretrage su ulazni tokeni zahtjeva i naplaćuju se zajedno s ostatkom prompta.

Usporedite planove

Kada se dnevne pretrage potroše

Zahtjev koji šalje web_search: true nakon zadnje dnevne pretrage ne odbija se. Dobiva odgovor bez pretrage: status je 200, a odgovor nema sources.

Pretraga kao vaš vlastiti alat

web_search: true jedini je prekidač ovdje opisane pretrage. Funkcija koju definirate u tools i nazovete web_search jedan je od vaših vlastitih alata: model vraća poziv, a vaš kod izvršava pretragu i šalje rezultat natrag.

Tipovi alata za pretragu drugih platformi, poput web_search_20250305 na /v1/messages ili {"type": "web_search"} na /v1/responses, ovdje ne pokreću pretragu.

Greške

Web pretraga ne dodaje statusni kod ni tip greške. Pretraga koja ništa ne pronađe, ili dan bez preostalih pretraga, daje normalan odgovor bez rezultata pretrage. Svaka druga greška ista je kao za zahtjev bez pretrage. Upravljanje greškama