Beépített webes keresés

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

A válasz közönséges chat completion, két kiegészítéssel. A válasz szögletes zárójeles számokkal hivatkozik a keresési eredményekre, a sources megmondja, melyik szám mit jelent, az annotations pedig jelöli, hol hivatkozik rájuk a szöveg:

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

A keresés bekapcsolása

A keresés a kérés egyik mezője, alapból ki van kapcsolva. Semmi nem keres, hacsak a kérés nem küldi.

A /v1/messages végponton a mező a törzs legfelső szintjén áll, a model és a messages mellett:

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

Mit csinál a keresett kérés

• Az API az utolsó user üzenetre keres a weben. A beszélgetés korábbi fordulói adják a keresés kontextusát.
• A keresés minden olyan kérésnél lefut, amely web_search: true értéket küld. A modell nem dönti el, hogy keressen-e.
• Az eredményeket számozott forrásokként a modell elé teszi, a modell pedig ezekből írja a válaszát.
• A válasz akkor indul, amikor a keresés kész. A streamelt kérés addig semmit nem küld, sem fejléceket, sem eseményeket, ezért az első chunk előtt számolj hosszabb várakozással.

Mit tartalmaz a válasz

• A válasz a végpontja szokásos alakját követi. A válasz a choices[0].message.content mezőben van (text blokk a /v1/messages végponton).
• A szöveg jelölőket hordozhat, például [1] és [2], az általuk alátámasztott állítások után. Minden szám egy olyan eredményt jelent, amelyet a modell elolvasott.
• A sources megnevezi ezeket az eredményeket: egy elem minden eredményhez, amelyet a modell megkapott, index, title és url mezővel. Az [1] jelölő az index 1 értékű elem. Azok az eredmények is szerepelnek, amelyekre a válasz nem hivatkozik.
• A /v1/chat/completions végponton az üzenetnek annotations mezője is van, OpenAI alakban: minden jelölő által megnevezett forráshoz egy url_citation, url, title, valamint start_index és end_index mezővel; ezek a jelölő helyét adják meg a content szövegében karakterekben számolva (a vég nem tartozik bele).
• Streamben a sources az utolsó chunkkal érkezik, a /v1/messages végponton pedig a message_delta eseménnyel. Az annotációk az utolsó előtti chunkban jönnek, delta.annotations néven.
• A sources csak akkor van jelen, ha a kérés keresése talált valamit. Az a válasz, amelyben nincs, keresési eredmények nélkül készült.

Hogyan számolódnak a keresések

Minden csomag napi meghatározott számú keresést tartalmaz:

• Az a kérés, amelynek a keresése talált valamit, a nap keretéből egy keresést használ el. Az a keresés, amely semmit nem talált, egyet sem.
• A chat és az API közösen használja a kulcs tulajdonos fiókjának keretét.
• A számolás minden nap 00:00 UTC-kor újraindul.
• A keresési eredmények a kérés bemeneti tokenjei, és a prompt többi részével együtt számlázódnak.

Csomagok összehasonlítása

Ha a nap keresései elfogytak

Az a kérés, amely a nap utolsó keresése után küld web_search: true értéket, nincs elutasítva. Keresés nélkül kap választ: a státusz 200, és a válaszban nincs sources.

Keresés saját eszközként

A web_search: true az itt leírt keresés egyetlen kapcsolója. Az a függvény, amelyet a tools mezőben definiálsz, és web_search néven nevezel el, a saját eszközöd: a modell hívást ad vissza, a kódod pedig lefuttatja a keresést, és visszaküldi az eredményt.

Más platformok keresőeszköz-típusai, például a web_search_20250305 a /v1/messages vagy a {"type": "web_search"} a /v1/responses végponton, itt nem indítanak keresést.

Hibák

A webes keresés nem ad hozzá státuszkódot és hibatípust. Az a keresés, amely semmit nem talál, vagy a keresések nélkül maradt nap keresési eredmények nélküli, normál választ ad. Minden más hiba ugyanaz, mint a keresés nélküli kérésnél. Hibakezelés