Veebiotsing

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

Vastus on tavaline vestluse täiendus (chat completion) kahe lisandiga. Vastus viitab otsingutulemustele nurksulgudes olevate numbritega, sources ütleb, mida iga number tähistab, ja annotations märgib, kus igaühele viidatakse:

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

Otsingu sisselülitamine

Otsing on päringu väli, vaikimisi väljas. Midagi ei otsita, kui päring seda ei saada.

Lõpp-punktis /v1/messages asub väli keha tipptasemel, model ja messages kõrval:

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

Mida otsinguga päring teeb

• API otsib veebist viimase kasutajasõnumi järgi. Vestluse varasemad pöörded annavad otsingule konteksti.
• Otsing käib igal päringul, mis saadab web_search: true. Mudel ei vali, kas otsida.
• Tulemused pannakse mudeli ette nummerdatud allikatena ja mudel kirjutab nende põhjal vastuse.
• Vastus algab, kui otsing on valmis. Voogedastatud päring ei saada selleni midagi, ei päiseid ega sündmusi, seega arvesta esimese chunkini pikema ooteajaga.

Mida vastus sisaldab

• Vastusel on oma lõpp-punkti tavaline kuju. Vastus on väljas choices[0].message.content (text plokk lõpp-punktis /v1/messages).
• Tekst võib sisaldada märgendeid nagu [1] ja [2] väidete järel, mida need toetavad. Iga number tähistab üht tulemust, mida mudel luges.
• sources nimetab need tulemused: üks kirje iga tulemuse kohta, mille mudel sai, väljadega index, title ja url. Märgend [1] on kirje, mille index on 1. Loetletud on ka tulemused, millele vastus ei viita.
• Lõpp-punktis /v1/chat/completions on sõnumil ka annotations, OpenAI kujul: üks url_citation iga allika kohta, mida märgend nimetab, väljadega url, title, start_index ja end_index, ehk märgendi asukoht väljas content märkides loetuna (lõppu ei arvestata).
• Voos tuleb sources viimase chunkiga ja lõpp-punktis /v1/messages sündmusega message_delta. Annotatsioonid tulevad ühes chunkis vahetult enne viimast, kujul delta.annotations.
• sources on olemas ainult siis, kui selle päringu otsing leidis midagi. Vastus ilma selleta kirjutati ilma otsingutulemusteta.

Kuidas otsinguid loetakse

Iga plaan sisaldab teatud arvu otsinguid päevas:

• Päring, mille otsing midagi leidis, kasutab ühe päeva limiidi otsingu. Otsing, mis midagi ei leidnud, ei kasuta ühtegi.
• Vestlus ja API jagavad võtme omaniku konto limiiti.
• Loendus algab uuesti iga päev kell 00:00 UTC.
• Otsingutulemused on päringu sisendtokenid ja arvestatakse ülejäänud promptiga.

Võrdle plaane

Kui päeva otsingud on otsas

Päringut, mis saadab web_search: true pärast päeva viimast otsingut, ei lükata tagasi. Sellele vastatakse ilma otsinguta: olek on 200 ja vastuses ei ole sources.

Otsing sinu enda tööriistana

web_search: true on siin kirjeldatud otsingu ainus lüliti. Funktsioon, mille määratled väljas tools ja nimetad web_search, on sinu enda tööriist: mudel tagastab kutse ning sinu kood teeb otsingu ja saadab tulemuse tagasi.

Teiste platvormide otsingutööriistade tüübid, näiteks web_search_20250305 lõpp-punktis /v1/messages või {"type": "web_search"} lõpp-punktis /v1/responses, ei käivita siin otsingut.

Vead

Veebiotsing ei lisa olekukoodi ega veatüüpi. Otsing, mis midagi ei leia, või päev, millel otsinguid enam ei ole, annab tavalise vastuse ilma otsingutulemusteta. Kõik muud vead on samad mis päringul ilma otsinguta. Vigade käsitlus