Vstavané webové vyhľadávanie

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

Odpoveď je bežné dokončenie chatu s dvoma doplnkami. Odpoveď odkazuje na výsledky vyhľadávania číslami v hranatých zátvorkách, sources hovorí, čo každé číslo zastupuje, a annotations označuje, kde sa každý z nich cituje:

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

Zapnutie vyhľadávania

Vyhľadávanie je pole requestu, predvolene vypnuté. Nič sa nevyhľadáva, pokiaľ to request neposlal.

Na /v1/messages je pole na najvyššej úrovni tela, vedľa model a messages:

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

Čo robí request s vyhľadávaním

• API vyhľadá na webe poslednú správu používateľa. Skoršie kroky konverzácie dávajú vyhľadávaniu kontext.
• Vyhľadávanie prebehne pri každom requeste, ktorý pošle web_search: true. Model nerozhoduje, či bude vyhľadávať.
• Výsledky sa predložia modelu ako očíslované zdroje a model z nich píše odpoveď.
• Odpoveď začne, keď je vyhľadávanie hotové. Streamovaný request dovtedy nepošle nič, ani hlavičky, ani udalosti, preto počítajte s dlhším čakaním pred prvým chunkom.

Čo odpoveď obsahuje

• Odpoveď má obvyklý tvar svojho endpointu. Odpoveď je v choices[0].message.content (blok text na /v1/messages).
• Text môže niesť značky ako [1] a [2] za tvrdeniami, ktoré podporujú. Každé číslo zastupuje jeden z výsledkov, ktoré model čítal.
• sources pomenúva tieto výsledky: jeden záznam pre každý výsledok, ktorý model dostal, s poľami index, title a url. Značka [1] je záznam s index 1. Uvedené sú aj výsledky, ktoré odpoveď necituje.
• Na /v1/chat/completions má správa aj annotations v tvare OpenAI: jednu url_citation pre každý zdroj, ktorý značka pomenúva, s poľami url, title, start_index a end_index, teda pozíciou značky v content počítanou v znakoch (koniec sa nezahŕňa).
• V streame príde sources s posledným chunkom a na /v1/messages s udalosťou message_delta. Annotations prídu v jednom chunku tesne pred posledným, ako delta.annotations.
• sources je prítomné, len ak vyhľadávanie tohto requestu niečo našlo. Odpoveď bez neho bola napísaná bez výsledkov vyhľadávania.

Ako sa vyhľadávania počítajú

Každý plán zahŕňa určitý počet vyhľadávaní za deň:

• Request, ktorého vyhľadávanie niečo našlo, použije jedno vyhľadávanie z denného limitu. Vyhľadávanie, ktoré nenašlo nič, nepoužije žiadne.
• Chat a API zdieľajú limit účtu, ktorý kľúč vlastní.
• Počet sa každý deň o 00:00 UTC začína znova.
• Výsledky vyhľadávania sú vstupné tokeny requestu a fakturujú sa spolu so zvyškom promptu.

Porovnať plány

Keď sú denné vyhľadávania vyčerpané

Request, ktorý pošle web_search: true po poslednom vyhľadávaní dňa, nie je odmietnutý. Odpovie sa naň bez vyhľadávania: status je 200 a odpoveď nemá sources.

Vyhľadávanie ako vlastný nástroj

web_search: true je jediný spínač vyhľadávania popísaného tu. Funkcia, ktorú definujete v tools a nazvete web_search, je jeden z vašich vlastných nástrojov: model vráti volanie a váš kód spustí vyhľadávanie a pošle výsledok späť.

Typy nástrojov vyhľadávania iných platforiem, ako web_search_20250305 na /v1/messages alebo {"type": "web_search"} na /v1/responses, tu vyhľadávanie nespustia.

Chyby

Webové vyhľadávanie nepridáva žiadny stavový kód ani typ chyby. Vyhľadávanie, ktoré nič nenájde, alebo deň bez zostávajúcich vyhľadávaní dá bežnú odpoveď bez výsledkov vyhľadávania. Každá iná chyba je rovnaká ako pri requeste bez vyhľadávania. Spracovanie chýb