Vgrajeno spletno iskanje

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čajen odgovor klepeta z dvema dodatkoma. Odgovor kaže na rezultate iskanja s številkami v oglatih oklepajih, sources pove, kaj pomeni posamezna številka, annotations pa označuje, kje je posamezen vir naveden:

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

Vklop iskanja

Iskanje je polje zahtevka, privzeto izklopljeno. Nič se ne išče, razen če ga zahtevek pošlje.

Na /v1/messages je polje na vrhnji ravni telesa, ob model in messages:

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

Kaj naredi zahtevek z iskanjem

• API išče po spletu za zadnje sporočilo uporabnika. Prejšnji obrati pogovora dajo iskanju kontekst.
• Iskanje teče pri vsakem zahtevku, ki pošlje web_search: true. Model ne izbira, ali bo iskal.
• Rezultati se postavijo pred model kot oštevilčeni viri, model pa iz njih napiše odgovor.
• Odgovor se začne, ko je iskanje končano. Zahtevek s pretakanjem do takrat ne pošlje ničesar, ne glav ne dogodkov, zato računajte na daljše čakanje pred prvim kosom.

Kaj vsebuje odgovor

• Odgovor ima običajno obliko svoje končne točke. Odgovor je v choices[0].message.content (blok text na /v1/messages).
• Besedilo lahko nosi oznake, kot sta [1] in [2], za trditvami, ki jih podpirajo. Vsaka številka predstavlja enega od rezultatov, ki jih je model prebral.
• sources poimenuje te rezultate: en vnos za vsak rezultat, ki ga je model dobil, z index, title in url. Oznaka [1] je vnos z index 1. Navedeni so tudi rezultati, ki jih odgovor ne navaja.
• Na /v1/chat/completions ima sporočilo tudi annotations v obliki OpenAI: en url_citation za vsak vir, ki ga poimenuje oznaka, z url, title ter start_index in end_index, to je položajem oznake v content, štetim v znakih (konec ni vključen).
• V toku pride sources z zadnjim kosom, na /v1/messages pa z dogodkom message_delta. Annotations pridejo v enem kosu tik pred zadnjim, kot delta.annotations.
• sources je prisoten le, če je iskanje tega zahtevka kaj našlo. Odgovor brez njega je bil napisan brez rezultatov iskanja.

Kako se iskanja štejejo

Vsak paket vključuje določeno število iskanj na dan:

• Zahtevek, pri katerem je iskanje nekaj našlo, porabi eno iskanje dnevne kvote. Iskanje, ki ni našlo nič, ne porabi nobenega.
• Klepet in API si delita kvoto računa, ki ima ključ v lasti.
• Štetje se vsak dan ob 00:00 UTC začne znova.
• Rezultati iskanja so vhodni tokeni zahtevka in se obračunajo skupaj z ostalim promptom.

Primerjajte pakete

Ko so dnevna iskanja porabljena

Zahtevek, ki pošlje web_search: true po zadnjem iskanju dneva, ni zavrnjen. Odgovori se nanj brez iskanja: status je 200, odgovor pa nima sources.

Iskanje kot lastno orodje

web_search: true je edino stikalo tukaj opisanega iskanja. Funkcija, ki jo definirate v tools in poimenujete web_search, je eno vaših lastnih orodij: model vrne klic, vaša koda pa izvede iskanje in pošlje rezultat nazaj.

Tipi orodij za iskanje drugih platform, kot sta web_search_20250305 na /v1/messages ali {"type": "web_search"} na /v1/responses, tu ne sprožijo iskanja.

Napake

Spletno iskanje ne doda statusne kode in ne tipa napake. Iskanje, ki ne najde nič, ali dan brez preostalih iskanj da običajen odgovor brez rezultatov iskanja. Vsaka druga napaka je enaka kot pri zahtevku brez iskanja. Obravnava napak