Sisäänrakennettu verkkohaku

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

Vastaus on tavallinen chat completion kahdella lisäyksellä. Vastaus viittaa hakutuloksiin hakasulkeissa olevilla numeroilla, sources kertoo, mitä kukin numero tarkoittaa, ja annotations merkitsee, missä kukin niistä mainitaan:

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

Haun kytkeminen päälle

Haku on pyynnön kenttä, oletuksena pois päältä. Mitään ei haeta, ellei pyyntö lähetä sitä.

Päätepisteessä /v1/messages kenttä on rungon ylimmällä tasolla, kenttien model ja messages vieressä:

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

Mitä haullinen pyyntö tekee

• API hakee verkosta viimeisen käyttäjän viestin perusteella. Keskustelun aiemmat vuorot antavat haulle sen kontekstin.
• Haku suoritetaan jokaisessa pyynnössä, joka lähettää web_search: true. Malli ei valitse, hakeeko se.
• Tulokset asetetaan mallin eteen numeroituina lähteinä, ja malli kirjoittaa vastauksensa niiden pohjalta.
• Vastaus alkaa, kun haku on valmis. Striimattu pyyntö ei lähetä mitään, ei otsakkeita eikä tapahtumia, ennen sitä, joten varaudu pidempään odotukseen ennen ensimmäistä chunkia.

Mitä vastaus sisältää

• Vastauksella on päätepisteensä tavallinen muoto. Vastaus on kentässä choices[0].message.content (text-lohko päätepisteessä /v1/messages).
• Tekstissä voi olla merkintöjä, kuten [1] ja [2], tukemiensa väitteiden perässä. Jokainen numero tarkoittaa yhtä tuloksista, jotka malli luki.
• sources nimeää nämä tulokset: yksi merkintä jokaista tulosta kohti, jonka malli sai, kentillä index, title ja url. Merkintä [1] on merkintä, jonka index on 1. Myös tulokset, joihin vastaus ei viittaa, luetellaan.
• Päätepisteessä /v1/chat/completions viestissä on myös annotations OpenAI:n muodossa: yksi url_citation jokaista lähdettä kohti, jonka merkintä nimeää, kentillä url, title, start_index ja end_index, eli merkinnän paikka kentässä content merkkeinä laskettuna (loppua ei lasketa mukaan).
• Striimissä sources tulee viimeisen chunkin mukana ja päätepisteessä /v1/messages tapahtuman message_delta mukana. Annotaatiot tulevat yhdessä chunkissa juuri ennen viimeistä muodossa delta.annotations.
• sources on mukana vain, jos tämän pyynnön haku löysi jotain. Vastaus ilman sitä kirjoitettiin ilman hakutuloksia.

Miten haut lasketaan

Jokaiseen tilaukseen kuuluu tietty määrä hakuja päivässä:

• Pyyntö, jonka haku löysi jotakin, käyttää yhden haun päivän kiintiöstä. Haku, joka ei löytänyt mitään, ei käytä yhtään.
• Chat ja API jakavat sen tilin kiintiön, joka omistaa avaimen.
• Laskenta alkaa uudelleen joka päivä kello 00:00 UTC.
• Hakutulokset ovat pyynnön syötetokeneita ja ne laskutetaan muun promptin mukana.

Vertaa tilauksia

Kun päivän haut on käytetty

Pyyntöä, joka lähettää web_search: true päivän viimeisen haun jälkeen, ei hylätä. Siihen vastataan ilman hakua: tila on 200, eikä vastauksessa ole sources-kenttää.

Haku omana työkalunasi

web_search: true on tässä kuvatun haun ainoa kytkin. Funktio, jonka määrittelet kentässä tools ja nimeät web_search, on yksi omista työkaluistasi: malli palauttaa kutsun, ja koodisi suorittaa haun ja lähettää tuloksen takaisin.

Muiden alustojen hakutyökalutyypit, kuten web_search_20250305 päätepisteessä /v1/messages tai {"type": "web_search"} päätepisteessä /v1/responses, eivät käynnistä hakua täällä.

Virheet

Verkkohaku ei lisää tilakoodia eikä virhetyyppiä. Haku, joka ei löydä mitään, tai päivä, jolloin hakuja ei ole jäljellä, tuottaa tavallisen vastauksen ilman hakutuloksia. Jokainen muu virhe on sama kuin pyynnössä ilman hakua. Virheiden käsittely