Preskoči na sadržaj
Pozivanje funkcija

Pozivanje funkcija

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

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

Primeri na ovoj stranici koriste /v1/chat/completions. Ista petlja radi na /v1/responses i /v1/messages; gde format nešto piše drugačije, odeljci ispod 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, sledeć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 sa tools, listom funkcija koje model može da zatraži.
2 Model Odgovor nosi tool_calls i finish_reason: "tool_calls". Svaki poziv navodi funkciju i daje njene argumente.
3 Vi Parsirajte arguments svakog poziva i izvršite svoju funkciju.
4 Vi Dodajte poruku asistenta i po jednu tool poruku za svaki poziv u messages, pa ponovo pošaljite zahtev sa istim tools.
5 Model Model odgovara tekstom sa finish_reason: "stop", ili traži još poziva. U tom slučaju vratite se na korak 3.

Jedan zahtev je jedan potez modela. API ne čuva razgovor između zahteva i ne postavlja broj rundi: vaš kod drži messages i odlučuje kada da stane.

Definisanje alata

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

Polje Tip Opis
type string Uvek 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 šema sa type: "object" na vrhu. Pogledajte Ključne reči šeme ispod.

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 da li model sme ili mora da pozove alat. Čita se samo zajedno sa tools.

Vrednost Opis Primenjuju
"auto" Model odlučuje da li će odgovoriti tekstom ili pozvati alat. Ovo je podrazumevano. Svi modeli
"required" Odgovor poziva bar jedan alat. Hostovani 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. Hostovani open-weight modeli

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

Sa required ili imenovanom funkcijom pročitajte finish_reason pre nego što pročitate tool_calls. Kada model ne proizvede poziv, odgovor je tekstualni sa finish_reason: "stop".

Značenje /v1/chat/completions /v1/responses /v1/messages
Model odlučuje "auto" "auto" {"type": "auto"}
Pozovi bar 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 potez bez poziva alata pošaljite zahtev bez tools.

Pozivi alata u odgovoru

Polje Tip Opis
finish_reason string tool_calls kada odgovor nosi bar 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 kog sledi 32 heksadecimalna znaka. Pošaljite ga nazad kao tool_call_id uz rezultat.
tool_calls[].type string Uvek 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 pre upotrebe.
message.content string | null null kada odgovor sadrži samo pozive. Hostovani open-weight modeli mogu da vrate tekst pored poziva; Shannon modeli vraćaju null.

Isti poziv u svakom formatu. Na /v1/responses to je stavka function_call u output, sa arguments kao JSON stringom. Na /v1/messages to je tool_use blok sadržaja čiji je input JSON objekat, njegov id počinje sa 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 potezu

Odgovor može da nosi više poziva. Izvršite svaki od njih i u sledećem zahtevu pošaljite po jedan rezultat za svaki poziv, svaki sa svojim tool_call_id.

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

Strimovani pozivi alata

Sa stream: true poziv stiže u jednom komadu: deo sadrži kompletan string arguments, pa nema fragmenata za spajanje. index broji pozive poteza od 0.

data: jedan deo, 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, sa pozivom u delta.tool_calls[0]. Poslednji deo ima finish_reason: "tool_calls" i usage.
/v1/responses Po pozivu: response.output_item.added (stavka function_call sa praznim arguments), response.function_call_arguments.delta (ceo string), response.function_call_arguments.done, response.output_item.done.
/v1/messages Po pozivu: content_block_start (tool_use blok sa praznim input), jedan content_block_delta čiji je input_json_delta.partial_json ceo 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 zahtev sa streamom koji nosi tools isporučuje tekst odgovora u jednom content delta-u na kraju poteza. Streaming

Slanje rezultata nazad

Drugi zahtev ponavlja razgovor i dodaje dve stvari: potez 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 potez asistenta nazad onako kako ste ga primili, pre rezultata. Svaki rezultat se povezuje sa svojim pozivom preko id-ja: 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 potezu asistenta function.arguments ostaje JSON string, tačno onako kako je stigao.
  • Razgovor može da se završi rezultatom alata. Nova korisnička poruka nije potrebna: model nastavlja od rezultata.
  • Kada vaša funkcija ne uspe, pošaljite grešku kao tekst rezultata. Model je tada može prijaviti ili zatražiti drugi poziv.

Ključne reči šeme

parameters (input_schema na /v1/messages) je JSON šema. Porodica Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) i hostovani 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 reči
Čita se kako je poslato Svaka ključna reč koja nije navedena u redovima ispod, na primer type, properties, required, items, enum, description, minimum, maximum, anyOf i allOf, na svakom nivou šeme.
format Čita se za vrednosti int32, int64, float, double, byte, date, date-time i enum.
oneOf Čita se kao anyOf.
Nije deo š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; druge vrednosti format.

Ponašanje i ograničenja

  • API ne postavlja maksimalan broj alata niti maksimalan broj rundi.
  • Telo zahteva može imati do 32 MiB, a razgovor sa rezultatima mora da stane u kontekstni prozor modela.
  • Kada zahtev nosi tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite i shannon-2-pro koriste podrazumevani temperature 0.2. Pošaljite temperature da postavite drugu vrednost.
  • Svaka runda je poseban zahtev: crpi vaše stanje i računa se u zaštitu od flooda kao i svaki drugi zahtev. Ograničenja i stanje

Greške

Poziv alata je običan odgovor sa statusom 200. Ove greške se tiču samog zahteva:

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: … Telo zahteva je veće od 32 MiB. Greška nosi code: "request_too_large".

Argumente piše model. Proverite ih prema svojoj šemi pre nego što izvršite funkciju, kao što biste proverili bilo koji spoljni ulaz.

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