Ugrás a tartalomra
Funkcióhívás

Funkcióhívás

Írd le a függvényeidet a kérésben, és a modell azokkal a hívásokkal válaszol, amelyeket végre akar hajtatni. A kódod futtatja őket, és visszaküldi az eredményeket: az API eszközhívásokat ad vissza, maga nem futtat eszközt.

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

Az oldal mintái a /v1/chat/completions végpontot használják. Ugyanez a ciklus fut a /v1/responses és a /v1/messages végponton is; ahol egy formátum másként írja le ugyanazt, az alábbi szakaszok mindhármat megmutatják.

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)

Az első válasz nem felel a kérdésre. Hívást kér:

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

Miután elküldted az eredményt, a következő válasz egy közönséges felelet: a message.content a szöveget tartalmazza, a finish_reason pedig stop.

A ciklus lépésről lépésre

Lépés Ki Mi történik
1 Te Küldd el a messages tömböt a tools mezővel együtt, amely azokat a függvényeket sorolja fel, amelyeket a modell kérhet.
2 Modell A válasz tool_calls mezőt és finish_reason: "tool_calls" értéket hordoz. Minden hívás megnevez egy függvényt, és megadja az argumentumait.
3 Te Értelmezd (parse) minden hívás arguments mezőjét, és futtasd a függvényedet.
4 Te Fűzd hozzá a messages tömbhöz az assistant üzenetet és hívásonként egy tool üzenetet, majd küldd el újra a kérést ugyanazzal a tools mezővel.
5 Modell A modell szöveggel válaszol finish_reason: "stop" értékkel, vagy további hívásokat kér. Ez utóbbi esetben menj vissza a 3. lépéshez.

Egy kérés egy modellforduló. Az API nem tart fenn beszélgetést a kérések között, és nem szab meg körszámot: a kódod tárolja a messages tömböt, és ő dönti el, mikor álljon le.

Eszközök megadása

A tools egy tömb, függvényenként egy elemmel. A katalógus minden modellje elfogadja; a GET /v1/models minden azonosítónál capabilities.tools: true értéket jelent.

Mező Típus Leírás
type string Mindig function.
function.name string A név, amelyet a modell használ, amikor ezt a függvényt kéri. Kötelező.
function.description string Mit csinál a függvény, közérthető nyelven.
function.parameters object Az argumentumok JSON Schema formában, a tetején type: "object" értékkel. Lásd lejjebb: Séma-kulcsszavak.

Minden végpontnak saját írásmódja van az eszközre. Azt küldd, amelyik a hívott végponthoz tartozik:

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

A tool_choice megadja, hogy a modell hívhat-e eszközt, vagy hívnia kell-e. Csak a tools mellett érvényes.

Érték Leírás Alkalmazza
"auto" A modell dönti el, hogy szöveggel válaszol, vagy eszközt hív. Ez az alapértelmezés. Minden modell
"required" A válasz legalább egy eszközt hív. Hosztolt nyílt súlyú modellek
{"type": "function", "function": {"name": "get_weather"}} A válasz ezt a függvényt hívja. A névnek a tools függvényei közül valónak kell lennie. A többi függvény hívásai kimaradnak a válaszból. Hosztolt nyílt súlyú modellek

A Shannon modellek (shannon-*) minden kérésnél maguk döntenek, mint auto esetén.

required vagy megnevezett függvény esetén a tool_calls olvasása előtt nézd meg a finish_reason értékét. Ha a modell nem hoz létre hívást, a válasz szöveges felelet finish_reason: "stop" értékkel.

Jelentés /v1/chat/completions /v1/responses /v1/messages
A modell dönt "auto" "auto" {"type": "auto"}
Legalább egy eszköz hívása "required" "required" {"type": "any"}
Egy megnevezett függvény hívása {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Kompatibilitás miatt elfogadott: tool_choice: "none" és parallel_tool_calls. Eszközhívás nélküli fordulóhoz küldd a kérést tools nélkül.

Eszközhívások a válaszban

Mező Típus Leírás
finish_reason string tool_calls, ha a válasz legalább egy hívást tartalmaz.
message.tool_calls array Hívásonként egy elem. A mező csak akkor szerepel, ha a modell hívást kért.
tool_calls[].id string A call_ után 32 hexadecimális karakter áll. Az eredménnyel együtt küldd vissza tool_call_id néven.
tool_calls[].type string Mindig function.
tool_calls[].function.name string A futtatandó függvény.
tool_calls[].function.arguments string Az argumentumok JSON-stringként, "{}", ha nincsenek. Használat előtt dolgozd fel.
message.content string | null null, ha a válasz csak hívásokat tartalmaz. A hosztolt nyílt súlyú modellek a hívások mellett szöveget is visszaadhatnak; a Shannon modellek null értéket adnak.

Ugyanaz a hívás minden formátumban. A /v1/responses végponton az output egy function_call eleme, az arguments pedig JSON-string. A /v1/messages végponton tool_use tartalmi blokk, amelynek input mezője JSON-objektum, az id értéke toolu_ előtaggal kezdődik, a stop_reason pedig 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\"}"
        }
      }
    ]
  }
}

Több hívás egy fordulóban

Egy válasz több hívást is hordozhat. Futtasd mindet, és a következő kérésben küldj hívásonként egy eredményt, mindegyiket a saját tool_call_id értékével.

A hosztolt nyílt súlyú modellek minden különböző hívást egyszer adnak vissza: két azonos nevű és azonos argumentumú hívás egyként érkezik.

Streamelt eszközhívások

stream: true esetén a hívás egy darabban érkezik: a chunk a teljes arguments stringet tartalmazza, így nincsenek összefűzendő töredékek. Az index a forduló hívásait számolja 0-tól.

data: egy chunk, formázva
{
  "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
    }
  ]
}
Végpont Mi érkezik
/v1/chat/completions Hívásonként egy chat.completion.chunk, a hívással a delta.tool_calls[0] mezőben. Az utolsó chunk finish_reason: "tool_calls" értéket és usage mezőt tartalmaz.
/v1/responses Hívásonként: response.output_item.added (üres arguments mezős function_call elem), response.function_call_arguments.delta (a teljes string), response.function_call_arguments.done, response.output_item.done.
/v1/messages Hívásonként: content_block_start (üres input mezős tool_use blokk), egy content_block_delta, amelynek input_json_delta.partial_json mezője a teljes argumentumszöveg, content_block_stop. Ezután a message_delta stop_reason: "tool_use" értéket hordoz.

A shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro és shannon-coder-1 modellen az a streamelt kérés, amely tools mezőt tartalmaz, a válaszszöveget egyetlen content deltában adja a forduló végén. Streaming

Eredmények visszaküldése

A második kérés megismétli a beszélgetést, és két dolgot ad hozzá: az assistant fordulót, amely a hívásokat kérte, és hívásonként egy eredményt.

{
  "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\"}"
    }
  ]
}
  • Az assistant fordulót úgy küldd vissza, ahogy kaptad, az eredmények előtt. Minden eredményt azonosító párosít a hívásához: tool_call_id a /v1/chat/completions, call_id a /v1/responses, tool_use_id a /v1/messages végponton.
  • Az eredmény szöveg. Szerializálj egy objektumot JSON-stringgé a content mezőhöz (a /v1/responses végponton az output mezőhöz). A /v1/messages végponton a tool_result blokk content mezője string vagy szövegblokkok listája.
  • Az assistant fordulóban a function.arguments JSON-string marad, pontosan úgy, ahogy megérkezett.
  • A beszélgetés végződhet eszközeredménnyel. Új user üzenet nem kell: a modell az eredménytől folytatja.
  • Ha a függvényed hibázik, a hibát küldd el az eredmény szövegeként. A modell ezután jelezheti, vagy másik hívást kérhet.

Séma-kulcsszavak

A parameters (a /v1/messages végponton input_schema) egy JSON Schema. A Shannon 3 család (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) és a hosztolt nyílt súlyú modellek úgy kapják meg, ahogy küldöd.

A shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro és shannon-coder-1 ezt a részhalmazt kapja meg, mindhárom végponton:

Kezelés Kulcsszavak
Úgy olvassa, ahogy küldted Minden kulcsszó, amelyet az alábbi sorok nem neveznek meg, például type, properties, required, items, enum, description, minimum, maximum, anyOf és allOf, a séma minden szintjén.
format Az int32, int64, float, double, byte, date, date-time és enum értékeket olvassa.
oneOf anyOf szerint olvassa.
Nem része annak a sémának, amelyet ezek a modellek kapnak $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; az exclusiveMinimum és az exclusiveMaximum, ha számok; a format egyéb értékei.

Viselkedés és korlátok

  • Az API nem szab meg legnagyobb eszközszámot, sem legnagyobb körszámot.
  • A kérés törzse legfeljebb 32 MiB lehet, és az eredményekkel együtt a beszélgetésnek bele kell férnie a modell kontextusablakába.
  • Ha a kérés tools mezőt tartalmaz, a shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite és shannon-2-pro 0.2 alapértelmezett temperature értéket használ. Más érték beállításához küldj temperature mezőt.
  • Minden kör külön kérés: az egyenlegedből vonódik, és mint bármely más kérés, beleszámít a flood protection korlátba. Korlátok és egyenleg

Hibák

Az eszközhívás rendes válasz 200-as státusszal. Ezek a hibák magát a kérést érintik:

Státusz Típus Üzenet Mikor
400 invalid_request_error unknown model: <id> A model nem szerepel a közzétett listában.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … A tools nem tömb, vagy egy másik mező JSON-típusa hibás.
413 invalid_request_error Failed to buffer the request body: … A kérés törzse nagyobb 32 MiB-nál. A hiba code: "request_too_large" értéket hordoz.

Az argumentumokat a modell írja. Ellenőrizd őket a sémád alapján, mielőtt futtatod a függvényt, mint bármilyen külső bemenetet.

A hitelesítési, egyenleg- és szerverhibák ugyanazok, mint minden kérésnél. Hibakezelés