Žiniatinklio paieška

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

Atsakymas yra įprastas pokalbio užbaigimas su dviem papildymais. Atsakymas skaičiais laužtiniuose skliaustuose nurodo paieškos rezultatus, sources pasako, ką žymi kiekvienas skaičius, o annotations pažymi, kur cituojamas kiekvienas jų:

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

Paieškos įjungimas

Paieška yra užklausos laukas, pagal nutylėjimą išjungtas. Nieko neieškoma, nebent užklausa jį siunčia.

Kelyje /v1/messages laukas yra aukščiausiame turinio lygyje, šalia model ir messages:

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

Ką daro užklausa su paieška

• API ieško internete pagal paskutinį naudotojo pranešimą. Ankstesni pokalbio ėjimai suteikia paieškai kontekstą.
• Paieška vykdoma kiekvienai užklausai, kuri siunčia web_search: true. Modelis nesprendžia, ar ieškoti.
• Rezultatai pateikiami modeliui kaip sunumeruoti šaltiniai, ir modelis iš jų parašo atsakymą.
• Atsakymas prasideda, kai paieška baigta. Srautinė užklausa iki tol nesiunčia nieko – nei antraščių, nei įvykių, todėl numatykite ilgesnį laukimą iki pirmojo gabalo.

Ką atsakymas talpina

• Atsakymas turi įprastą savo galinio taško formą. Atsakymas yra choices[0].message.content (text blokas kelyje /v1/messages).
• Tekste po teiginių, kuriuos jie patvirtina, gali būti žymeklių, pavyzdžiui, [1] ir [2]. Kiekvienas skaičius žymi vieną iš modelio perskaitytų rezultatų.
• sources įvardija tuos rezultatus: po vieną įrašą kiekvienam modeliui perduotam rezultatui, su index, title ir url. Žymeklis [1] yra įrašas, kurio index yra 1. Rezultatai, kurių atsakymas necituoja, taip pat įtraukti į sąrašą.
• Galiniame taške /v1/chat/completions pranešime taip pat yra annotations OpenAI formatu: po vieną url_citation kiekvienam šaltiniui, kurį įvardija žymeklis, su url, title, taip pat start_index ir end_index – žymeklio padėtimi content simboliais (pabaiga neįskaičiuojama).
• Sraute sources ateina su paskutiniu gabalu, o galiniame taške /v1/messages – su įvykiu message_delta. Anotacijos ateina viename gabale prieš pat paskutinįjį, kaip delta.annotations.
• sources yra tik tada, kai šios užklausos paieška ką nors rado. Atsakymas be jo parašytas be paieškos rezultatų.

Kaip skaičiuojamos paieškos

Kiekvienas planas apima tam tikrą paieškų per dieną skaičių:

• Užklausa, kurios paieška ką nors rado, sunaudoja vieną dienos limito paiešką. Paieška, kuri nieko nerado, nesunaudoja jokios.
• Pokalbis ir API dalijasi raktą turinčios paskyros limitu.
• Skaičiavimas kasdien 00:00 UTC prasideda iš naujo.
• Paieškos rezultatai yra užklausos įvesties tokenai ir apmokestinami kartu su likusiu nurodymu.

Palyginti planus

Kai dienos paieškos išnaudotos

Užklausa, siunčianti web_search: true po paskutinės dienos paieškos, neatmetama. Į ją atsakoma be paieškos: būsena yra 200, o atsakyme nėra sources.

Paieška kaip jūsų pačių įrankis

web_search: true yra vienintelis čia aprašytos paieškos jungiklis. Funkcija, kurią apibrėžiate tools ir pavadinate web_search, yra vienas jūsų pačių įrankių: modelis grąžina kreipinį, o jūsų kodas atlieka paiešką ir grąžina rezultatą.

Kitų platformų paieškos įrankių tipai, pavyzdžiui, web_search_20250305 kelyje /v1/messages arba {"type": "web_search"} kelyje /v1/responses, čia paieškos nepaleidžia.

Klaidos

Paieška internete nepridėda nei būsenos kodo, nei klaidos tipo. Paieška, kuri nieko nerado, arba diena be likusių paieškų duoda įprastą atsakymą be paieškos rezultatų. Kiekviena kita klaida tokia pati kaip užklausai be paieškos. Klaidų tvarkymas