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 izvršava i šalje rezultate natrag: API vraća pozive alata i sam ne izvršava 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 format nešto zapisuje 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. 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 Tko Što se događa
1 Vi Pošaljite messages zajedno s tools, popisom funkcija koje model smije tražiti.
2 Model Odgovor nosi tool_calls i finish_reason: "tool_calls". Svaki poziv navodi funkciju i daje njezine argumente.
3 Vi Parsirajte arguments svakog poziva i izvršite svoju funkciju.
4 Vi Dodajte poruku asistenta i jednu poruku tool po pozivu u messages, zatim ponovno 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 okret modela. API ne čuva razgovor između zahtjeva i ne postavlja broj krugova: vaš kod drži messages i odlučuje kada stati.

Definiranje alata

tools je niz s jednim unosom po funkciji. Prihvaća ga svaki model 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 Što funkcija radi, običnim jezikom.
function.parameters object Argumenti kao JSON Schema s type: "object" na vrhu. Pogledajte Ključne riječi sheme 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 kaže smije li model, ili mora li, pozvati alat. Čita se samo zajedno s tools.

Vrijednost Opis Primjenjuju
"auto" Model odlučuje hoće li odgovoriti tekstom ili pozvati alat. Ovo je zadano. 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 s auto.

S required ili imenovanom funkcijom pročitajte finish_reason prije nego pročitate tool_calls. Kada model ne proizvede nijedan poziv, odgovor je tekstualni 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 okret bez poziva alata pošaljite zahtjev bez tools.

Pozivi alata u odgovoru

Polje Tip Opis
finish_reason string tool_calls kada odgovor nosi barem jedan poziv.
message.tool_calls array Jedan unos po pozivu. Polje je prisutno samo kada je model zatražio poziv.
tool_calls[].id string call_ iza kojeg slijedi 32 heksadecimalna znaka. Pošaljite ga natrag kao tool_call_id s rezultatom.
tool_calls[].type string Uvijek function.
tool_calls[].function.name string Funkcija koju treba izvršiti.
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 uz pozive vratiti tekst; 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 objekt, 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\"}"
        }
      }
    ]
  }
}

Nekoliko poziva u jednom okretu

Odgovor može nositi nekoliko poziva. Izvršite svaki od njih i u sljedećem zahtjevu pošaljite jedan rezultat po pozivu, 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.

Streamani pozivi alata

S stream: true poziv stiže u jednom komadu: chunk sadrži cijeli string arguments, pa nema fragmenata za spajanje. index broji pozive okreta 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 Što stiže
/v1/chat/completions Jedan chat.completion.chunk po pozivu, s pozivom u delta.tool_calls[0]. Zadnji 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 streamani zahtjev koji nosi tools isporučuje tekst odgovora u jednoj delti content na kraju okreta. Streaming

Slanje rezultata natrag

Drugi zahtjev ponavlja razgovor i dodaje dvije stvari: okret asistenta koji je tražio pozive i jedan rezultat po pozivu.

{
  "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 okret asistenta natrag onako kako ste ga primili, prije rezultata. Svaki rezultat povezuje se s pozivom po id-u: tool_call_id na /v1/chat/completions, call_id na /v1/responses, tool_use_id na /v1/messages.
  • Rezultat je tekst. Serijalizirajte objekt u JSON string za content (output na /v1/responses). Na /v1/messages content bloka tool_result je string ili popis tekstualnih blokova.
  • U okretu asistenta function.arguments ostaje JSON string, toč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 zatražiti drugi poziv.

Ključne riječi sheme

parameters (input_schema na /v1/messages) je JSON Schema. Obitelj 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:

Postupanje Ključne riječi
Čita se kako je poslano Svaka ključna riječ koja nije navedena u recima u nastavku, na primjer type, properties, required, items, enum, description, minimum, maximum, anyOf i allOf, na svakoj razini sheme.
format Čita se za vrijednosti int32, int64, float, double, byte, date, date-time i enum.
oneOf Čita se kao anyOf.
Nije dio sheme koju ti 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; druge vrijednosti format.

Ponašanje i ograničenja

  • API ne postavlja najveći broj alata ni najveći broj krugova.
  • Tijelo zahtjeva može imati do 32 MiB, a razgovor s rezultatima mora stati u kontekstni prozor modela.
  • Kada zahtjev nosi tools, 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: crpi iz vašeg stanja i broji se u flood protection kao i svaki drugi zahtjev. Ograničenja i stanje

Greške

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

Status Tip Poruka Kada
400 invalid_request_error unknown model: <id> model nije id s objavljenog popisa.
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 veće je od 32 MiB. Greška nosi code: "request_too_large".

Argumente piše model. Provjerite ih prema svojoj shemi prije izvršavanja funkcije, kao i svaki vanjski ulaz.

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