Zum Inhalt sprangen
Funktiounsofruff

Funktiounsofruff

Beschreift Är Funktiounen an der Ufro, an de Modell äntwert mat de Ruffer, déi en wëll hunn. Äre Code féiert se aus a schéckt d'Resultater zréck: d'API gëtt Tool-Ruffer zréck a féiert selwer kee Tool aus.

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

D'Beispiller op dëser Säit benotzen /v1/chat/completions. Déiselwecht Loop leeft op /v1/responses an /v1/messages; wou e Format eppes anescht schreift, weisen d'Rubriken ënnen all dräi.

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)

Déi éischt Äntwert beäntwert d'Fro net. Si freet no engem Ruff:

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

Nodeems Dir d'Resultat geschéckt hutt, ass déi nächst Äntwert eng normal Äntwert: message.content enthält den Text an finish_reason ass stop.

D'Loop, Schrëtt fir Schrëtt

Schrëtt Wien Wat geschitt
1 Dir Schéckt messages zesumme mat tools, der Lëscht vun de Funktiounen, no deenen de Modell däerf froen.
2 Modell D'Äntwert enthält tool_calls an finish_reason: "tool_calls". All Ruff nennt eng Funktioun a gëtt hir Argumenter.
3 Dir Parst d'arguments vun all Ruff a féiert Är Funktioun aus.
4 Dir Hänkt d'Assistent-Message an eng tool-Message pro Ruff u messages un, a schéckt dann d'Ufro nach eng Kéier mat deene selwechte tools.
5 Modell De Modell äntwert mat Text a mat finish_reason: "stop", oder freet no weidere Ruffer. An deem Fall gitt zréck zu Schrëtt 3.

Eng Ufro ass een Tour vum Modell. D'API behält keng Konversatioun tëscht Ufroen an setzt keng Zuel u Ronnen: Äre Code hält messages a entscheet, wéini en opheiert.

Tools definéieren

tools ass en Array mat engem Eintrag pro Funktioun. All Modell vum Katalog akzeptéiert et; GET /v1/models mellt capabilities.tools: true fir all ID.

Feld Typ Beschreiwung
type string Ëmmer function.
function.name string Den Numm, deen de Modell benotzt, wann en no dëser Funktioun freet. Erfuerderlech.
function.description string Wat d'Funktioun mécht, a ganz normaler Sprooch.
function.parameters object D'Argumenter als JSON Schema mat type: "object" uewen. Kuckt Schema-Schlësselwierder ënnen.

All Endpoint huet seng eege Schreifweis fir en Tool. Schéckt déi, déi zum Endpoint gehéiert, deen Dir rufft:

{
  "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 seet, ob de Modell en Tool däerf, oder muss, ruffen. Et gëtt nëmmen zesumme mat tools gelies.

Wäert Beschreiwung Ugewannt vun
"auto" De Modell entscheet, ob en mat Text äntwert oder en Tool rifft. Dat ass de Standard. All Modeller
"required" D'Äntwert rifft op d'mannst een Tool. Hosted Open-Weight-Modeller
{"type": "function", "function": {"name": "get_weather"}} D'Äntwert rifft dës Funktioun. Den Numm muss eng vun de Funktiounen an tools sinn. Ruffer vun aneren Funktioune ginn aus der Äntwert erausgelooss. Hosted Open-Weight-Modeller

D'Shannon-Modeller (shannon-*) entscheeden bei all Ufro selwer, wéi bei auto.

Liest bei required oder enger genannter Funktioun finish_reason, ier Dir tool_calls liest. Wann de Modell keen Ruff produzéiert, ass d'Äntwert eng Textäntwert mat finish_reason: "stop".

Bedeitung /v1/chat/completions /v1/responses /v1/messages
De Modell entscheet "auto" "auto" {"type": "auto"}
Op d'mannst een Tool ruffen "required" "required" {"type": "any"}
Eng genannt Funktioun ruffen {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Fir d'Kompatibilitéit akzeptéiert: tool_choice: "none" an parallel_tool_calls. Fir en Tour ouni Tool-Ruffer schéckt d'Ufro ouni tools.

Tool-Ruffer an der Äntwert

Feld Typ Beschreiwung
finish_reason string tool_calls, wann d'Äntwert op d'mannst een Ruff enthält.
message.tool_calls array Een Eintrag pro Ruff. D'Feld ass nëmmen do, wann de Modell no engem Ruff gefrot huet.
tool_calls[].id string call_ gefollegt vun 32 hexadezimale Zeechen. Schéckt se als tool_call_id mam Resultat zréck.
tool_calls[].type string Ëmmer function.
tool_calls[].function.name string D'Funktioun, déi soll lafen.
tool_calls[].function.arguments string D'Argumenter als JSON-String, "{}", wann et keng gëtt. Parst se virun der Notzung.
message.content string | null null, wann d'Äntwert just Ruffer enthält. D'Hosted Open-Weight-Modeller kënnen Text niewent de Ruffer zréckgi; d'Shannon-Modeller ginn null zréck.

Deeselwechte Ruff an all Format. Op /v1/responses ass et en function_call-Item vun output, mat arguments als JSON-String. Op /v1/messages ass et e tool_use-Inhaltsblock, dee säin input als JSON-Objet huet, seng id fänkt mat toolu_ un, an stop_reason ass 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\"}"
        }
      }
    ]
  }
}

Méi Ruffer an engem Tour

Eng Äntwert ka méi Ruffer enthalen. Féiert se all aus a schéckt an der nächster Ufro ee Resultat pro Ruff, all mat sengem eegenen tool_call_id.

D'Hosted Open-Weight-Modeller ginn all verschidde Ruff eemol zréck: zwee Ruffer mam selwechten Numm a mat de selwechten Argumenter kommen als een un.

Gestreamt Tool-Ruffer

Mat stream: true kënnt e Ruff an engem Stéck: de Chunk enthält de kompletten arguments-String, sou datt et keng Fragmenter ze verbannen gëtt. index zielt d'Ruffer vum Tour vun 0 un.

data: ee Chunk, formatéiert
{
  "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 Wat ukënnt
/v1/chat/completions Ee chat.completion.chunk pro Ruff, mam Ruff an delta.tool_calls[0]. Dee leschte Chunk huet finish_reason: "tool_calls" an usage.
/v1/responses Pro Ruff: response.output_item.added (e function_call-Item mat eidelen arguments), response.function_call_arguments.delta (de ganze String), response.function_call_arguments.done, response.output_item.done.
/v1/messages Pro Ruff: content_block_start (e tool_use-Block mat eidelem input), een content_block_delta, dee säin input_json_delta.partial_json de ganzen Argumenter-Text ass, content_block_stop. message_delta enthält dann stop_reason: "tool_use".

Bei shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1 liwwert eng gestreamt Ufro mat tools hiren Äntwert-Text an engem content-Delta um Enn vum Tour. Streaming

Resultater zréckschécken

Déi zweet Ufro widderhëlt d'Konversatioun a füügt zwee Saachen derbäi: den Assistent-Tour, deen d'Ruffer ugefrot huet, an ee Resultat pro Ruff.

{
  "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\"}"
    }
  ]
}
  • Schéckt den Assistent-Tour esou zréck, wéi Dir en kritt hutt, virun de Resultater. All Resultat gëtt iwwer d'ID mat sengem Ruff verbonnen: tool_call_id op /v1/chat/completions, call_id op /v1/responses, tool_use_id op /v1/messages.
  • E Resultat ass Text. Serialiséiert en Objet an e JSON-String fir content (output op /v1/responses). Op /v1/messages ass de content vun engem tool_result-Block e String oder eng Lëscht vun Textblöck.
  • Am Assistent-Tour bleift function.arguments e JSON-String, genau sou wéi en ukomm ass.
  • D'Konversatioun däerf mat engem Tool-Resultat ophalen. Et brauch keng nei Benotzer-Message: de Modell mécht vum Resultat aus weider.
  • Wann Är Funktioun feelschléit, schéckt de Feeler als Resultat-Text. De Modell ka sech dann doriwwer äusseren oder en anere Ruff ufroen.

Schema-Schlësselwierder

parameters (input_schema op /v1/messages) ass e JSON Schema. D'Shannon-3-Famill (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) an d'Hosted Open-Weight-Modeller kréien et esou, wéi Dir et schéckt.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1 kréien dës Ënnermengt, op allen dräi Endpoints:

Behandlung Schlësselwierder
Gelies wéi geschéckt All Schlësselwuert, dat net an den Zeilen ënnendrënner genannt ass, zum Beispill type, properties, required, items, enum, description, minimum, maximum, anyOf an allOf, op all Niveau vum Schema.
format Gëtt fir d'Wäerter int32, int64, float, double, byte, date, date-time an enum gelies.
oneOf Gëtt als anyOf gelies.
Kee Bestanddeel vum Schema, dat dës Modeller kréien $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 an exclusiveMaximum, wa se Zuelen sinn; aner Wäerter vun format.

Verhalen a Limiten

  • D'API setzt keng Maximalzuel u Tools a keng Maximalzuel u Ronnen.
  • E Body vun enger Ufro däerf bis zu 32 MiB grouss sinn, an d'Konversatioun mat hire Resultater muss an d'Kontextfënster vum Modell passen.
  • Wann eng Ufro tools enthält, benotze shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite an shannon-2-pro en Standard-temperature vun 0.2. Schéckt temperature, fir en anere Wäert ze setzen.
  • All Ronn ass eng eege Ufro: si hëlt aus Ärem Solde an zielt fir de Flood-Schutz wéi all aner Ufro. Limiten a Solde

Feeler

E Tool-Ruff ass eng normal Äntwert mam Status 200. Dës Feeler betreffen d'Ufro selwer:

Status Typ Message Wéini
400 invalid_request_error unknown model: <id> model ass keng ID vun der publizéierter Lëscht.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools ass kee Array, oder en anert Feld huet de falsche JSON-Typ.
413 invalid_request_error Failed to buffer the request body: … De Body vun der Ufro ass méi grouss wéi 32 MiB. De Feeler enthält code: "request_too_large".

De Modell schreift d'Argumenter. Kontrolléiert se géint Äert Schema, ier Dir d'Funktioun ausféiert, wéi Dir all aneren externen Input géif kontrolléieren.

Authentifikatioun, Solde a Serverfeeler sinn déi selwecht wéi bei all Ufro. Feelerbehandlung