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 uglastim zagradama, sources kaže šta koji broj označava, a annotations označava gdje se svaki navodi:

{
  "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 je zahtjev pošalje.

Na /v1/messages polje stoji na najvišem nivou tijela, pored model i messages:

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

Šta radi zahtjev s pretragom

• API pretražuje web za posljednju korisničku poruku. Raniji krugovi razgovora daju pretrazi kontekst.
• Pretraga se pokreće na svaki zahtjev koji šalje web_search: true. Model ne bira hoće li pretraživati.
• Rezultati se stavljaju pred model kao numerisani 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 duže čekanje prije prvog chunka.

Šta odgovor sadrži

• Odgovor ima uobičajen oblik svog endpointa. Odgovor je u choices[0].message.content (blok text na /v1/messages).
• Tekst može nositi oznake kao što su [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 dat modelu, s index, title i url. Oznaka [1] je unos s index 1. Navedeni su i rezultati koje odgovor ne navodi.
• Na /v1/chat/completions poruka ima i annotations, u OpenAI obliku: jedan url_citation za svaki izvor koji imenuje oznaka, s url, title, te start_index i end_index, pozicijom oznake u content brojanom u znakovima (kraj nije uključen).
• U streamu sources dolazi s posljednjim chunkom, a na /v1/messages s događajem message_delta. Anotacije dolaze u jednom chunku neposredno prije posljednjeg, kao delta.annotations.
• sources postoji samo ako je pretraga ovog zahtjeva nešto našla. Odgovor bez njega napisan je bez rezultata pretrage.

Kako se pretrage broje

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

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

Uporedite planove

Kada se dnevne pretrage potroše

Zahtjev koji šalje web_search: true nakon posljednje pretrage u danu ne odbija se. Odgovara se bez pretrage: status je 200, a odgovor nema sources.

Pretraga kao vlastiti alat

web_search: true je jedini 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 pokreće pretragu i šalje rezultat nazad.

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

Greške

Pretraga weba ne dodaje nijedan statusni kod ni tip greške. Pretraga koja ne nađe ništa, ili dan bez preostalih pretraga, daje običan odgovor bez rezultata pretrage. Svaka druga greška ista je kao za zahtjev bez pretrage. Upravljanje greškama