Web bilaketa

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

Erantzuna chat completion arrunt bat da, bi gehigarrirekin. Erantzunak bilaketa-emaitzetara seinalatzen du kortxete artean dauden zenbakiekin, sources-ek zenbaki bakoitza zeri dagokion esaten du, eta annotations-ek bakoitza non aipatzen den markatzen du:

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

Bilaketa aktibatzea

Bilaketa eskaeraren eremu bat da, lehenespenez desaktibatua. Ez da ezer bilatzen eskaera batek bidaltzen ez badu.

/v1/messages-en eremua gorputzaren goiko mailan dago, model eta messages-en ondoan:

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

Bilaketa duen eskaera batek zer egiten duen

• APIak azken erabiltzaile-mezua bilatzen du webean. Elkarrizketaren aurreko txandek bilaketari testuingurua ematen diote.
• Bilaketa web_search: true bidaltzen duen eskaera guztietan exekutatzen da. Modeloak ez du aukeratzen bilatu behar duen ala ez.
• Emaitzak modeloaren aurrean iturri zenbakitu gisa jartzen dira, eta modeloak horietatik idazten du erantzuna.
• Erantzuna bilaketa amaitzen denean hasten da. Streamean doan eskaera batek ez du ezer bidaltzen, ez goiburuak ez gertaerak, ordura arte, beraz kontuan hartu lehen chunk-a baino lehen itxaronaldi luzeagoa izan daitekeela.

Erantzunak zer duen

• Erantzunak bere endpointaren ohiko forma du. Erantzuna choices[0].message.content-en dago (text bloke bat /v1/messages-en).
• Testuak [1] eta [2] bezalako markak eduki ditzake, onartzen dituzten esaldien ondoren. Zenbaki bakoitzak modeloak irakurritako emaitzetako bat adierazten du.
• sources-ek emaitza horiek izendatzen ditu: sarrera bat modeloak jaso duen emaitza bakoitzeko, index, title eta url eremuekin. [1] marka index 1 duen sarrera da. Erantzunak aipatzen ez dituen emaitzak ere zerrendatzen dira.
• /v1/chat/completions-en mezuak annotations ere badu, OpenAI-ren formarekin: url_citation bat marka batek izendatzen duen iturri bakoitzeko, url, title, start_index eta end_index eremuekin; azken biak markaren posizioa dira content-en, karaktere kopuruan zenbatuta (amaiera ez dago barne).
• Stream batean sources azken chunk-arekin etortzen da, eta /v1/messages-en message_delta gertaerarekin. Oharrak azkenaren aurreko chunk batean datoz, delta.annotations gisa.
• sources dago eskaera honen bilaketak zerbait aurkitu badu bakarrik. Hura gabeko erantzuna bilaketa-emaitzarik gabe idatzi zen.

Bilaketak nola kontatzen diren

Plan guztiek egunean bilaketa-kopuru bat barne hartzen dute:

• Bilaketak ezer aurkitu duen eskaera batek egunaren kopuruko bilaketa bat erabiltzen du. Ezer aurkitu ez duen bilaketak ez du bat ere erabiltzen.
• Txatak eta APIak giltzaren jabea den kontuaren kopuru bera partekatzen dute.
• Kontaketa egunero hasten da berriro 00:00 UTC-n.
• Bilaketa-emaitzak eskaeraren sarrera-tokenak dira eta promptaren gainerakoarekin batera kobratzen dira.

Alderatu planak

Egunaren bilaketak agortu direnean

Eguneko azken bilaketaren ondoren web_search: true bidaltzen duen eskaera bat ez da errefusatzen. Bilaketarik gabe erantzuten zaio: egoera 200 da eta erantzunak ez du sources-ik.

Bilaketa zure tresna propio gisa

web_search: true hemen deskribatutako bilaketaren etengailu bakarra da. tools-en definitzen duzun eta web_search izena duen funtzio bat zure tresna propioetako bat da: modeloak dei bat itzultzen du, eta zure kodeak bilaketa exekutatzen du eta emaitza bidaltzen du berriro.

Beste plataformen bilaketa-tresna motek, adibidez /v1/messages-en web_search_20250305 edo /v1/responses-en {"type": "web_search"}, ez dute hemen bilaketarik hasten.

Erroreak

Web bilaketak ez du egoera-koderik ez errore-motarik gehitzen. Ezer aurkitzen ez duen bilaketa batek, edo bilaketarik gelditzen ez den egun batek, erantzun normala ematen du bilaketa-emaitzarik gabe. Gainerako errore guztiak bilaketarik gabeko eskaera batean bezalakoak dira. Errore‑kudeaketa