Kërkim i integruar në ueb

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

Përgjigjja është një chat completion i zakonshëm me dy shtesa. Përgjigjja u referohet rezultateve të kërkimit me numra në kllapa katrore, sources tregon se çfarë përfaqëson çdo numër, dhe annotations shënon ku citohet secili:

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

Aktivizimi i kërkimit

Kërkimi është fushë e kërkesës, e çaktivizuar si parazgjedhje. Nuk kërkohet asgjë përveç nëse një kërkesë e dërgon.

Në /v1/messages fusha qëndron në nivelin e sipërm të trupit, pranë model dhe messages:

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

Çfarë bën një kërkesë me kërkim

• API-ja kërkon në ueb për mesazhin e fundit të përdoruesit. Radhët e mëparshme të bisedës ia japin kërkimit kontekstin.
• Kërkimi ekzekutohet në çdo kërkesë që dërgon web_search: true. Modeli nuk zgjedh nëse do të kërkojë.
• Rezultatet vendosen para modelit si burime të numëruara, dhe modeli e shkruan përgjigjen e tij nga ato.
• Përgjigjja fillon kur kërkimi mbaron. Një kërkesë me stream nuk dërgon asgjë, as header-a as ngjarje, deri atëherë, prandaj llogaritni një pritje më të gjatë para pjesës së parë.

Çfarë përmban përgjigjja

• Përgjigjja ka formën e zakonshme të endpoint-it të vet. Përgjigjja është te choices[0].message.content (një bllok text në /v1/messages).
• Teksti mund të mbajë shenja si [1] dhe [2] pas pohimeve që mbështesin. Çdo numër përfaqëson një nga rezultatet që lexoi modeli.
• sources emërton ato rezultate: një hyrje për çdo rezultat që iu dha modelit, me index, title dhe url. Shenja [1] është hyrja me index 1. Janë renditur edhe rezultatet që përgjigjja nuk i citon.
• Te /v1/chat/completions mesazhi ka edhe annotations, në formën e OpenAI: një url_citation për çdo burim që emërton një shenjë, me url, title, si dhe start_index dhe end_index, pozicionin e shenjës te content të numëruar në karaktere (fundi nuk përfshihet).
• Në një stream sources vjen me pjesën e fundit, dhe te /v1/messages me ngjarjen message_delta. Annotations vijnë në një pjesë pak para të fundit, si delta.annotations.
• sources ekziston vetëm nëse kërkimi i kësaj kërkese gjeti diçka. Një përgjigje pa të u shkrua pa rezultate kërkimi.

Si numërohen kërkimet

Çdo plan përfshin një numër kërkimesh në ditë:

• Një kërkesë, kërkimi i së cilës gjeti diçka, përdor një kërkim nga kuota e ditës. Një kërkim që nuk gjeti asgjë nuk përdor asnjë.
• Biseda dhe API e ndajnë kuotën e llogarisë që e zotëron çelësin.
• Numërimi fillon përsëri çdo ditë në 00:00 UTC.
• Rezultatet e kërkimit janë tokens hyrjeje të kërkesës dhe faturohen me pjesën tjetër të prompt-it.

Krahasoni planet

Kur kërkimet e ditës shterojnë

Një kërkesë që dërgon web_search: true pas kërkimit të fundit të ditës nuk refuzohet. Merr përgjigje pa kërkim: statusi është 200 dhe përgjigjja nuk ka sources.

Kërkimi si mjet i juaji

web_search: true është çelësi i vetëm i kërkimit të përshkruar këtu. Një funksion që e përcaktoni te tools dhe e emërtoni web_search është një nga mjetet tuaja: modeli kthen një thirrje, dhe kodi juaj e ekzekuton kërkimin dhe dërgon rezultatin mbrapsht.

Llojet e mjeteve të kërkimit të platformave të tjera, si web_search_20250305 në /v1/messages ose {"type": "web_search"} në /v1/responses, nuk nisin kërkim këtu.

Gabimet

Kërkimi në ueb nuk shton kod statusi dhe as lloj gabimi. Një kërkim që nuk gjen asgjë, ose një ditë pa kërkime të mbetura, jep një përgjigje normale pa rezultate kërkimi. Çdo gabim tjetër është i njëjtë si për një kërkesë pa kërkim. Trajtimi i gabimeve