Ενσωματωμένη αναζήτηση ιστού

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

Η απάντηση είναι ένα συνηθισμένο chat completion με δύο προσθήκες. Η απάντηση παραπέμπει στα αποτελέσματα αναζήτησης με αριθμούς σε αγκύλες, το sources λέει τι αντιπροσωπεύει κάθε αριθμός και το annotations σημειώνει πού παρατίθεται το καθένα:

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

Ενεργοποίηση της αναζήτησης

Η αναζήτηση είναι πεδίο του αιτήματος, απενεργοποιημένο από προεπιλογή. Τίποτα δεν αναζητείται εκτός αν το στείλει ένα αίτημα.

Στο /v1/messages το πεδίο βρίσκεται στο ανώτατο επίπεδο του σώματος, δίπλα στα model και messages:

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

Τι κάνει ένα αίτημα με αναζήτηση

• Το API αναζητά στον ιστό για το τελευταίο μήνυμα χρήστη. Οι προηγούμενοι γύροι της συνομιλίας δίνουν στην αναζήτηση το πλαίσιό της.
• Η αναζήτηση τρέχει σε κάθε αίτημα που στέλνει web_search: true. Το μοντέλο δεν επιλέγει αν θα κάνει αναζήτηση.
• Τα αποτελέσματα τοποθετούνται μπροστά στο μοντέλο ως αριθμημένες πηγές, και το μοντέλο γράφει την απάντησή του από αυτά.
• Η απάντηση ξεκινά όταν τελειώσει η αναζήτηση. Ένα αίτημα με streaming δεν στέλνει τίποτα, ούτε κεφαλίδες ούτε συμβάντα, μέχρι τότε, οπότε υπολογίστε μεγαλύτερη αναμονή πριν από το πρώτο chunk.

Τι περιέχει η απάντηση

• Η απάντηση έχει τη συνηθισμένη μορφή του endpoint της. Η απάντηση βρίσκεται στο choices[0].message.content (block text στο /v1/messages).
• Το κείμενο μπορεί να φέρει δείκτες όπως [1] και [2] μετά τους ισχυρισμούς που στηρίζουν. Κάθε αριθμός αντιστοιχεί σε ένα από τα αποτελέσματα που διάβασε το μοντέλο.
• Το sources ονομάζει αυτά τα αποτελέσματα: μία εγγραφή για κάθε αποτέλεσμα που δόθηκε στο μοντέλο, με index, title και url. Ο δείκτης [1] είναι η εγγραφή με index 1. Αναφέρονται και τα αποτελέσματα που η απάντηση δεν παραθέτει.
• Στο /v1/chat/completions το μήνυμα έχει επίσης annotations, στη μορφή του OpenAI: ένα url_citation για κάθε πηγή που κατονομάζει ένας δείκτης, με url, title, καθώς και start_index και end_index, τη θέση του δείκτη στο content μετρημένη σε χαρακτήρες (το τέλος δεν περιλαμβάνεται).
• Σε ένα stream το sources έρχεται με το τελευταίο chunk και στο /v1/messages με το γεγονός message_delta. Οι σημειώσεις έρχονται σε ένα chunk αμέσως πριν από το τελευταίο, ως delta.annotations.
• Το sources υπάρχει μόνο αν η αναζήτηση αυτού του αιτήματος βρήκε κάτι. Μια απάντηση χωρίς αυτό γράφτηκε χωρίς αποτελέσματα αναζήτησης.

Πώς μετρώνται οι αναζητήσεις

Κάθε πλάνο περιλαμβάνει έναν αριθμό αναζητήσεων ανά ημέρα:

• Ένα αίτημα του οποίου η αναζήτηση βρήκε κάτι χρησιμοποιεί μία αναζήτηση από το ημερήσιο όριο. Μια αναζήτηση που δεν βρήκε τίποτα δεν χρησιμοποιεί καμία.
• Το chat και το API μοιράζονται το όριο του λογαριασμού στον οποίο ανήκει το κλειδί.
• Η μέτρηση ξεκινά ξανά κάθε μέρα στις 00:00 UTC.
• Τα αποτελέσματα αναζήτησης είναι tokens εισόδου του αιτήματος και χρεώνονται μαζί με το υπόλοιπο prompt.

Σύγκριση πλάνων

Όταν εξαντληθούν οι αναζητήσεις της ημέρας

Ένα αίτημα που στέλνει web_search: true μετά την τελευταία αναζήτηση της ημέρας δεν απορρίπτεται. Απαντάται χωρίς αναζήτηση: η κατάσταση είναι 200 και η απάντηση δεν έχει sources.

Η αναζήτηση ως δικό σας εργαλείο

Το web_search: true είναι ο μόνος διακόπτης της αναζήτησης που περιγράφεται εδώ. Μια συνάρτηση που ορίζετε στο tools και ονομάζετε web_search είναι ένα από τα δικά σας εργαλεία: το μοντέλο επιστρέφει μια κλήση και ο κώδικάς σας εκτελεί την αναζήτηση και στέλνει πίσω το αποτέλεσμα.

Τύποι εργαλείων αναζήτησης άλλων πλατφορμών, όπως το web_search_20250305 στο /v1/messages ή το {"type": "web_search"} στο /v1/responses, δεν ξεκινούν αναζήτηση εδώ.

Σφάλματα

Η αναζήτηση στον ιστό δεν προσθέτει κωδικό κατάστασης ούτε τύπο σφάλματος. Μια αναζήτηση που δεν βρίσκει τίποτα, ή μια ημέρα χωρίς αναζητήσεις που απομένουν, δίνει κανονική απάντηση χωρίς αποτελέσματα αναζήτησης. Κάθε άλλο σφάλμα είναι ίδιο με ένα αίτημα χωρίς αναζήτηση. Χειρισμός σφαλμάτων