Ricerca web integrata

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

La risposta è un normale chat completion con due aggiunte. Il testo rimanda ai risultati della ricerca con numeri tra parentesi quadre, sources indica a cosa corrisponde ogni numero e annotations segna dove ciascuno è citato:

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

Attivare la ricerca

La ricerca è un campo della richiesta, disattivato per impostazione predefinita. Non si cerca nulla a meno che una richiesta non lo invii.

Su /v1/messages il campo sta al livello superiore del corpo, accanto a model e messages:

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

Cosa fa una richiesta con ricerca

• L'API cerca sul web in base all'ultimo messaggio dell'utente. I turni precedenti della conversazione danno alla ricerca il suo contesto.
• La ricerca viene eseguita a ogni richiesta che invia web_search: true. Il modello non sceglie se cercare.
• I risultati vengono messi davanti al modello come fonti numerate, e il modello scrive la sua risposta a partire da essi.
• La risposta inizia quando la ricerca è finita. Una richiesta in streaming non invia nulla, né header né eventi, fino a quel momento, quindi metti in conto un'attesa più lunga prima del primo chunk.

Cosa contiene la risposta

• La risposta ha la forma abituale del suo endpoint. La risposta è in choices[0].message.content (un blocco text su /v1/messages).
• Il testo può contenere marcatori come [1] e [2] dopo le affermazioni che sostengono. Ogni numero corrisponde a uno dei risultati letti dal modello.
• sources nomina quei risultati: una voce per ogni risultato dato al modello, con index, title e url. Il marcatore [1] è la voce con index 1. Sono elencati anche i risultati che la risposta non cita.
• Su /v1/chat/completions il messaggio ha anche annotations, nella forma OpenAI: un url_citation per ogni fonte nominata da un marcatore, con url, title, start_index e end_index, la posizione del marcatore in content contata in caratteri (la fine è esclusa).
• In uno stream sources arriva con l'ultimo chunk e su /v1/messages con l'evento message_delta. Le annotazioni arrivano in un chunk poco prima dell'ultimo, come delta.annotations.
• sources è presente solo se la ricerca di questa richiesta ha trovato qualcosa. Una risposta senza di esso è stata scritta senza risultati di ricerca.

Come vengono contate le ricerche

Ogni piano include un certo numero di ricerche al giorno:

• Una richiesta la cui ricerca ha trovato qualcosa usa una ricerca della quota giornaliera. Una ricerca che non ha trovato nulla non ne usa alcuna.
• Chat e API condividono la quota dell'account che possiede la chiave.
• Il conteggio riparte ogni giorno alle 00:00 UTC.
• I risultati della ricerca sono token di input della richiesta e vengono fatturati insieme al resto del prompt.

Confronta i piani

Quando le ricerche del giorno sono esaurite

Una richiesta che invia web_search: true dopo l'ultima ricerca del giorno non viene rifiutata. Riceve risposta senza ricerca: lo stato è 200 e la risposta non ha sources.

La ricerca come tool tuo

web_search: true è l'unico interruttore della ricerca qui descritta. Una funzione che definisci in tools e chiami web_search è uno dei tuoi tool: il modello restituisce una chiamata, e il tuo codice esegue la ricerca e rimanda il risultato.

I tipi di tool di ricerca di altre piattaforme, come web_search_20250305 su /v1/messages o {"type": "web_search"} su /v1/responses, qui non avviano una ricerca.

Errori

La ricerca web non aggiunge alcun codice di stato né alcun tipo di errore. Una ricerca che non trova nulla, o un giorno senza ricerche rimaste, dà una normale risposta senza risultati di ricerca. Ogni altro errore è uguale a quello di una richiesta senza ricerca. Gestione errori