Websoektog

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

Die antwoord is 'n gewone klets-voltooiing met twee toevoegings. Die antwoord verwys met nommers in vierkantige hakies na die soekresultate, sources sê waarvoor elke nommer staan, en annotations merk waar elkeen aangehaal word:

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

Soektog aanskakel

Soektog is 'n veld van die versoek, by verstek af. Niks word deursoek tensy 'n versoek dit stuur nie.

Op /v1/messages sit die veld op die boonste vlak van die liggaam, langs model en messages:

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

Wat 'n versoek met soektog doen

• Die API deursoek die web vir die laaste gebruikersboodskap. Vroeëre beurte van die gesprek gee die soektog sy konteks.
• Die soektog loop op elke versoek wat web_search: true stuur. Die model kies nie of dit soek nie.
• Die resultate word as genommerde bronne voor die model geplaas, en die model skryf sy antwoord daaruit.
• Die antwoord begin wanneer die soektog klaar is. 'n Gestroomde versoek stuur tot dan niks nie, nóg headers nóg gebeure, so laat voorsiening vir 'n langer wag voor die eerste chunk.

Wat die antwoord bevat

• Die antwoord het die gewone vorm van sy eindpunt. Die antwoord is in choices[0].message.content ('n text-blok op /v1/messages).
• Die teks kan merkers soos [1] en [2] dra ná die stellings wat hulle ondersteun. Elke nommer staan vir een van die resultate wat die model gelees het.
• sources noem daardie resultate: een inskrywing vir elke resultaat wat aan die model gegee is, met index, title en url. Die merker [1] is die inskrywing met index 1. Resultate wat die antwoord nie aanhaal nie, word ook gelys.
• Op /v1/chat/completions het die boodskap ook annotations, in die OpenAI-vorm: een url_citation vir elke bron wat 'n merker noem, met url, title, en start_index en end_index, die posisie van die merker in content in karakters getel (die einde is nie ingesluit nie).
• In 'n stroom kom sources saam met die laaste chunk, en op /v1/messages saam met die message_delta-gebeurtenis. Die annotasies kom in een chunk net voor die laaste een, as delta.annotations.
• sources is net daar as die soektog van hierdie versoek iets gevind het. 'n Antwoord daarsonder is sonder soekresultate geskryf.

Hoe soektogte getel word

Elke plan sluit 'n aantal soektogte per dag in:

• 'n Versoek waarvan die soektog iets gevind het, gebruik een soektog van die dag se toelaat. 'n Soektog wat niks gevind het nie, gebruik geen.
• Klets en API deel die toelaat van die rekening wat die sleutel besit.
• Die telling begin elke dag weer om 00:00 UTC.
• Die soekresultate is insettokens van die versoek en word saam met die res van die prompt gefaktureer.

Vergelyk die planne

Wanneer die dag se soektogte opgebruik is

'n Versoek wat web_search: true stuur ná die laaste soektog van die dag, word nie geweier nie. Dit word sonder 'n soektog beantwoord: die status is 200 en die antwoord het geen sources nie.

Soektog as 'n gereedskap van jou eie

web_search: true is die enigste skakelaar van die soektog wat hier beskryf word. 'n Funksie wat jy in tools definieer en web_search noem, is een van jou eie gereedskap: die model gee 'n oproep terug, en jou kode voer die soektog uit en stuur die resultaat terug.

Soekgereedskaptipes van ander platforms, soos web_search_20250305 op /v1/messages of {"type": "web_search"} op /v1/responses, begin hier nie 'n soektog nie.

Foute

Websoektog voeg geen statuskode en geen foutipe by nie. 'n Soektog wat niks vind nie, of 'n dag sonder oorblywende soektogte, gee 'n gewone antwoord sonder soekresultate. Elke ander fout is dieselfde as vir 'n versoek sonder soektog. Fouthantering