Preskoči na sadržaj
Pozivanje funkcija

Pozivanje funkcija

Opišite svoje funkcije u zahtjevu, a model odgovara pozivima koje želi izvršiti. Vaš kod ih pokreće i šalje rezultate nazad: API vraća pozive alata i sam ne pokreće nijedan alat.

POST https://api.shannon-ai.com/v1/chat/completions

Primjeri na ovoj stranici koriste /v1/chat/completions. Ista petlja radi na /v1/responses i /v1/messages; gdje neki format nešto piše drugačije, odjeljci u nastavku prikazuju sva tri.

import json
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, for example Paris"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["city"],
        },
    },
}]

def get_weather(city, unit="celsius"):
    # Your code: ask a weather service here.
    return {"city": city, "temperature": 18, "unit": unit, "conditions": "cloudy"}

messages = [{"role": "user", "content": "What is the weather in Paris right now?"}]
answer = None

for _ in range(5):  # the API sets no limit on rounds: set your own
    response = client.chat.completions.create(
        model="Kimi-K3-3BIT-REAP",
        messages=messages,
        tools=tools,
    )
    choice = response.choices[0]
    if choice.finish_reason != "tool_calls":
        answer = choice.message.content
        break

    messages.append(choice.message)  # the assistant turn with its tool_calls
    for call in choice.message.tool_calls:
        args = json.loads(call.function.arguments)  # arguments is a JSON string
        result = get_weather(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

print(answer)

Prvi odgovor ne odgovara na pitanje. On traži poziv:

200 JSON
{
  "id": "chatcmpl-5b0c1d8e7f6a4b3c9d2e1f0a8b7c6d5e",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "reasoning_content": "The user asks for the current weather in Paris. I should call get_weather.",
        "tool_calls": [
          {
            "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Paris\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 312,
    "completion_tokens": 58,
    "total_tokens": 370,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 31}
  }
}

Nakon što pošaljete rezultat, sljedeći odgovor je običan odgovor: message.content sadrži tekst, a finish_reason je stop.

Petlja, korak po korak

Korak Ko Šta se dešava
1 Vi Pošaljite messages zajedno s tools, listom funkcija koje model smije tražiti.
2 Model Odgovor sadrži tool_calls i finish_reason: "tool_calls". Svaki poziv imenuje funkciju i daje njene argumente.
3 Vi Parsirajte arguments svakog poziva i pokrenite svoju funkciju.
4 Vi Dodajte poruku asistenta i po jednu tool poruku za svaki poziv u messages, pa ponovo pošaljite zahtjev s istim tools.
5 Model Model odgovara tekstom s finish_reason: "stop", ili traži još poziva. U tom slučaju vratite se na korak 3.

Jedan zahtjev je jedan krug modela. API ne čuva razgovor između zahtjeva i ne postavlja broj krugova: vaš kod drži messages i odlučuje kada će stati.

Definiranje alata

tools je niz s jednim unosom po funkciji. Prihvata ga svaki model iz kataloga; GET /v1/models za svaki id prijavljuje capabilities.tools: true.

Polje Tip Opis
type string Uvijek function.
function.name string Ime koje model koristi kada traži ovu funkciju. Obavezno.
function.description string Šta funkcija radi, običnim jezikom.
function.parameters object Argumenti kao JSON Schema sa type: "object" na vrhu. Pogledajte Ključne riječi šeme u nastavku.

Svaki endpoint ima svoj zapis alata. Pošaljite onaj koji pripada endpointu koji pozivate:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "City name, for example Paris"
        },
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
      },
      "required": ["city"]
    }
  }
}

tool_choice

tool_choice određuje smije li model, ili mora li, pozvati alat. Čita se samo zajedno s tools.

Vrijednost Opis Primjenjuje
"auto" Model odlučuje hoće li odgovoriti tekstom ili pozvati alat. Ovo je zadana vrijednost. Svi modeli
"required" Odgovor poziva barem jedan alat. Hostirani open-weight modeli
{"type": "function", "function": {"name": "get_weather"}} Odgovor poziva ovu funkciju. Ime mora biti jedna od funkcija u tools. Pozivi drugih funkcija izostavljaju se iz odgovora. Hostirani open-weight modeli

Shannon modeli (shannon-*) odlučuju u svakom zahtjevu, kao kod auto.

Uz required ili imenovanu funkciju, pročitajte finish_reason prije nego što pročitate tool_calls. Kada model ne napravi nijedan poziv, odgovor je tekstualni odgovor s finish_reason: "stop".

Značenje /v1/chat/completions /v1/responses /v1/messages
Model odlučuje "auto" "auto" {"type": "auto"}
Pozovi barem jedan alat "required" "required" {"type": "any"}
Pozovi jednu imenovanu funkciju {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Prihvaćeno radi kompatibilnosti: tool_choice: "none" i parallel_tool_calls. Za krug bez poziva alata pošaljite zahtjev bez tools.

Pozivi alata u odgovoru

Polje Tip Opis
finish_reason string tool_calls kada odgovor sadrži barem jedan poziv.
message.tool_calls array Jedan unos po pozivu. Polje postoji samo kada je model tražio poziv.
tool_calls[].id string call_ iza kojeg slijedi 32 heksadecimalna znaka. Vratite ga kao tool_call_id zajedno s rezultatom.
tool_calls[].type string Uvijek function.
tool_calls[].function.name string Funkcija koju treba pokrenuti.
tool_calls[].function.arguments string Argumenti kao JSON string, "{}" kada ih nema. Parsirajte ga prije upotrebe.
message.content string | null null kada odgovor sadrži samo pozive. Hostirani open-weight modeli mogu vratiti tekst uz pozive; Shannon modeli vraćaju null.

Isti poziv u svakom formatu. Na /v1/responses to je stavka function_call u output, s arguments kao JSON stringom. Na /v1/messages to je blok sadržaja tool_use čiji je input JSON objekat, njegov id počinje s toolu_, a stop_reason je tool_use.

{
  "finish_reason": "tool_calls",
  "message": {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Paris\"}"
        }
      }
    ]
  }
}

Više poziva u jednom krugu

Odgovor može sadržavati više poziva. Pokrenite svaki od njih i u sljedećem zahtjevu pošaljite po jedan rezultat za svaki poziv, svaki sa svojim tool_call_id.

Hostirani open-weight modeli vraćaju svaki različit poziv jednom: dva poziva s istim imenom i istim argumentima stižu kao jedan.

Streamovani pozivi alata

Uz stream: true, poziv stiže u jednom komadu: chunk sadrži kompletan string arguments, pa nema fragmenata koje treba spajati. index broji pozive kruga od 0.

data: jedan chunk, formatiran
{
  "id": "chatcmpl-5b0c1d8e7f6a4b3c9d2e1f0a8b7c6d5e",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "delta": {
        "tool_calls": [
          {
            "index": 0,
            "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Paris\"}"
            }
          }
        ]
      },
      "finish_reason": null
    }
  ]
}
Endpoint Šta stiže
/v1/chat/completions Jedan chat.completion.chunk po pozivu, s pozivom u delta.tool_calls[0]. Posljednji chunk ima finish_reason: "tool_calls" i usage.
/v1/responses Po pozivu: response.output_item.added (stavka function_call s praznim arguments), response.function_call_arguments.delta (cijeli string), response.function_call_arguments.done, response.output_item.done.
/v1/messages Po pozivu: content_block_start (blok tool_use s praznim input), jedan content_block_delta čiji je input_json_delta.partial_json cijeli tekst argumenata, content_block_stop. message_delta zatim nosi stop_reason: "tool_use".

Na shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro i shannon-coder-1, streamovani zahtjev koji sadrži tools isporučuje tekst odgovora u jednoj content delti na kraju kruga. Streaming

Slanje rezultata nazad

Drugi zahtjev ponavlja razgovor i dodaje dvije stvari: krug asistenta koji je tražio pozive i po jedan rezultat za svaki poziv.

{
  "messages": [
    {"role": "user", "content": "What is the weather in Paris right now?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\":\"Paris\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
      "content": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"
    }
  ]
}
  • Pošaljite krug asistenta nazad onako kako ste ga primili, prije rezultata. Svaki rezultat se uparuje sa svojim pozivom preko id-a: tool_call_id na /v1/chat/completions, call_id na /v1/responses, tool_use_id na /v1/messages.
  • Rezultat je tekst. Serijalizujte objekat u JSON string za content (output na /v1/responses). Na /v1/messages, content bloka tool_result je string ili lista tekstualnih blokova.
  • U krugu asistenta, function.arguments ostaje JSON string, tačno onako kako je stigao.
  • Razgovor može završiti rezultatom alata. Nova korisnička poruka nije potrebna: model nastavlja od rezultata.
  • Kada vaša funkcija ne uspije, pošaljite grešku kao tekst rezultata. Model je tada može prijaviti ili tražiti drugi poziv.

Ključne riječi šeme

parameters (input_schema na /v1/messages) je JSON Schema. Porodica Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) i hostirani open-weight modeli primaju je onako kako je pošaljete.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro i shannon-coder-1 primaju ovaj podskup, na sva tri endpointa:

Obrada Ključne riječi
Čita se onako kako je poslano Svaka ključna riječ koja nije navedena u redovima ispod, na primjer type, properties, required, items, enum, description, minimum, maximum, anyOf i allOf, na svakom nivou šeme.
format Čita se za vrijednosti int32, int64, float, double, byte, date, date-time i enum.
oneOf Čita se kao anyOf.
Nije dio šeme koju ovi modeli primaju $schema, $id, $ref, $defs, $comment, definitions, additionalProperties, unevaluatedProperties, patternProperties, propertyNames, examples, default, title, const, not, if, then, else, contains, minContains, maxContains, dependentRequired, dependentSchemas, dependencies, readOnly, writeOnly, deprecated, contentEncoding, contentMediaType, contentSchema, multipleOf, uniqueItems; exclusiveMinimum i exclusiveMaximum kada su brojevi; ostale vrijednosti format.

Ponašanje i ograničenja

  • API ne postavlja najveći broj alata niti najveći broj krugova.
  • Tijelo zahtjeva može imati do 32 MiB, a razgovor sa svojim rezultatima mora stati u kontekstni prozor modela.
  • Kada zahtjev sadrži tools, modeli shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite i shannon-2-pro koriste zadani temperature od 0.2. Pošaljite temperature da postavite drugu vrijednost.
  • Svaki krug je zaseban zahtjev: tereti vaše stanje i računa se u flood zaštitu kao i svaki drugi zahtjev. Ograničenja i stanje

Greške

Poziv alata je običan odgovor sa statusom 200. Ove greške se odnose na sam zahtjev:

Status Tip Poruka Kada
400 invalid_request_error unknown model: <id> model nije id sa objavljene liste.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools nije niz, ili drugo polje ima pogrešan JSON tip.
413 invalid_request_error Failed to buffer the request body: … Tijelo zahtjeva je veće od 32 MiB. Greška sadrži code: "request_too_large".

Argumente piše model. Provjerite ih prema svojoj šemi prije nego što pokrenete funkciju, kao što biste provjerili bilo koji vanjski ulaz.

Greške autentikacije, stanja i servera iste su kao za svaki zahtjev. Upravljanje greškama