Aqbeż għall-kontenut
Sejħiet ta' Funzjonijiet

Sejħiet ta' Funzjonijiet

Iddeskrivi l-funzjonijiet tiegħek fit-talba u l-mudell iwieġeb bis-sejħiet li jrid li jsiru. Il-kodiċi tiegħek iħaddimhom u jibgħat ir-riżultati lura: l-API tagħti lura sejħiet ta' tools u ma tħaddem l-ebda tool waħedha.

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

L-eżempji f'din il-paġna jużaw /v1/chat/completions. L-istess ċiklu jaħdem fuq /v1/responses u /v1/messages; fejn format jikteb xi ħaġa b'mod differenti, it-taqsimiet hawn taħt juru t-tlieta.

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)

L-ewwel tweġiba ma twieġibx il-mistoqsija. Titlob sejħa:

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

Wara li tibgħat ir-riżultat, it-tweġiba li jmiss hija tweġiba ordinarja: message.content iżomm it-test u finish_reason huwa stop.

Iċ-ċiklu, pass pass

Pass Min X'jiġri
1 Inti Ibgħat messages flimkien ma' tools, il-lista ta' funzjonijiet li l-mudell jista' jitlob.
2 Mudell It-tweġiba ġġorr tool_calls u finish_reason: "tool_calls". Kull sejħa tisemmi funzjoni u tagħti l-argumenti tagħha.
3 Inti Parsja l-arguments ta' kull sejħa u ħaddem il-funzjoni tiegħek.
4 Inti Żid il-messaġġ tal-assistent u messaġġ tool wieħed għal kull sejħa ma' messages, imbagħad ibgħat it-talba mill-ġdid bl-istess tools.
5 Mudell Il-mudell iwieġeb bit-test b'finish_reason: "stop", jew jitlob aktar sejħiet. F'dak il-każ erġa' lura għall-pass 3.

Talba waħda hija turn wieħed tal-mudell. L-API ma żżomm l-ebda konversazzjoni bejn it-talbiet u ma tistabbilixxi l-ebda numru ta' rounds: il-kodiċi tiegħek iżomm messages u jiddeċiedi meta jieqaf.

Kif tiddefinixxi tools

tools huwa array b'daħla waħda għal kull funzjoni. Kull mudell tal-katalgu jaċċettah; GET /v1/models jirrapporta capabilities.tools: true għal kull id.

Qasam Tip Deskrizzjoni
type string Dejjem function.
function.name string L-isem li l-mudell juża meta jitlob din il-funzjoni. Meħtieġ.
function.description string X'tagħmel il-funzjoni, b'lingwa sempliċi.
function.parameters object L-argumenti bħala JSON Schema b'type: "object" fil-quċċata. Ara Keywords tal-schema hawn taħt.

Kull endpoint għandu l-ikteb tiegħu ta' tool. Ibgħat dak li jagħmel parti mill-endpoint li tsejjaħ:

{
  "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 jgħid jekk il-mudell jistax, jew għandux, isejjaħ tool. Jinqara biss flimkien ma' tools.

Valur Deskrizzjoni Applikat minn
"auto" Il-mudell jiddeċiedi jekk iwieġebx bit-test jew jekk isejjaħx tool. Dan huwa d-default. Il-mudelli kollha
"required" It-tweġiba tsejjaħ tool wieħed jew aktar. Mudelli open-weight ospitati
{"type": "function", "function": {"name": "get_weather"}} It-tweġiba tsejjaħ din il-funzjoni. L-isem irid ikun waħda mill-funzjonijiet f'tools. Is-sejħiet għal funzjonijiet oħra jitħallew barra mit-tweġiba. Mudelli open-weight ospitati

Il-mudelli Shannon (shannon-*) jiddeċiedu f'kull talba, bħal b'auto.

B'required jew b'funzjoni msemmija, aqra finish_reason qabel taqra tool_calls. Meta l-mudell ma jipproduċi l-ebda sejħa, it-tweġiba hija tweġiba bit-test b'finish_reason: "stop".

Tifsira /v1/chat/completions /v1/responses /v1/messages
Il-mudell jiddeċiedi "auto" "auto" {"type": "auto"}
Sejjaħ tool wieħed jew aktar "required" "required" {"type": "any"}
Sejjaħ funzjoni waħda msemmija {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Aċċettati għall-kompatibbiltà: tool_choice: "none" u parallel_tool_calls. Għal turn mingħajr sejħiet ta' tools, ibgħat it-talba mingħajr tools.

Sejħiet ta' tools fit-tweġiba

Qasam Tip Deskrizzjoni
finish_reason string tool_calls meta t-tweġiba ġġorr sejħa waħda jew aktar.
message.tool_calls array Daħla waħda għal kull sejħa. Il-qasam huwa preżenti biss meta l-mudell talab sejħa.
tool_calls[].id string call_ segwit minn 32 karattru eżadeċimali. Ibgħat lura bħala tool_call_id mar-riżultat.
tool_calls[].type string Dejjem function.
tool_calls[].function.name string Il-funzjoni li għandha taħdem.
tool_calls[].function.arguments string L-argumenti bħala string JSON, "{}" meta ma jkun hemm l-ebda wieħed. Parsja qabel ma tużah.
message.content string | null null meta t-tweġiba fiha biss sejħiet. Il-mudelli open-weight ospitati jistgħu jagħtu test maġenb is-sejħiet; il-mudelli Shannon jagħtu null.

L-istess sejħa f'kull format. Fuq /v1/responses hija element function_call ta' output, b'arguments bħala string JSON. Fuq /v1/messages hija blokk tal-kontenut tool_use li l-input tiegħu huwa oġġett JSON, l-id tiegħu jibda b'toolu_, u stop_reason huwa 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\"}"
        }
      }
    ]
  }
}

Diversi sejħiet f'turn wieħed

Tweġiba tista' ġġorr diversi sejħiet. Ħaddem kull waħda minnhom u ibgħat riżultat wieħed għal kull sejħa, kull wieħed bit-tool_call_id tiegħu, fit-talba li jmiss.

Il-mudelli open-weight ospitati jagħtu lura kull sejħa distinta darba waħda: żewġ sejħiet bl-istess isem u bl-istess argumenti jaslu bħala waħda.

Sejħiet ta' tools fi stream

B'stream: true, sejħa tasal f'biċċa waħda: il-chunk iżomm l-string kompluta ta' arguments, għalhekk ma hemm l-ebda frammenti x'tgħaqqad. index jgħodd is-sejħiet tat-turn minn 0.

data: chunk wieħed, iffurmattjat
{
  "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 X'jasal
/v1/chat/completions chat.completion.chunk wieħed għal kull sejħa, bis-sejħa f'delta.tool_calls[0]. L-aħħar chunk għandu finish_reason: "tool_calls" u usage.
/v1/responses Għal kull sejħa: response.output_item.added (element function_call b'arguments vojta), response.function_call_arguments.delta (l-string kollha), response.function_call_arguments.done, response.output_item.done.
/v1/messages Għal kull sejħa: content_block_start (blokk tool_use b'input vojt), content_block_delta wieħed li l-input_json_delta.partial_json tiegħu huwa t-test sħiħ tal-argumenti, content_block_stop. message_delta imbagħad iġorr stop_reason: "tool_use".

Fuq shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro u shannon-coder-1, talba fi stream li ġġorr tools twassal it-test tat-tweġiba tagħha f'delta content waħda fl-aħħar tat-turn. Streaming

Kif tibgħat ir-riżultati lura

It-tieni talba terġa' tibgħat il-konversazzjoni u żżid żewġ affarijiet: it-turn tal-assistent li talab is-sejħiet, u riżultat wieħed għal kull sejħa.

{
  "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\"}"
    }
  ]
}
  • Ibgħat it-turn tal-assistent lura kif irċevejtu, qabel ir-riżultati. Kull riżultat jiġi akkoppjat mas-sejħa tiegħu bl-id: tool_call_id fuq /v1/chat/completions, call_id fuq /v1/responses, tool_use_id fuq /v1/messages.
  • Riżultat huwa test. Serjalizza oġġett f'string JSON għal content (output fuq /v1/responses). Fuq /v1/messages il-content ta' blokk tool_result huwa string jew lista ta' blokki tat-test.
  • Fit-turn tal-assistent, function.arguments jibqa' string JSON, eżattament kif wasal.
  • Il-konversazzjoni tista' tispiċċa b'riżultat ta' tool. Ma hemm bżonn l-ebda messaġġ ġdid tal-utent: il-mudell ikompli mir-riżultat.
  • Meta l-funzjoni tiegħek tfalli, ibgħat il-falliment bħala t-test tar-riżultat. Il-mudell imbagħad jista' jirrapportah jew jitlob sejħa oħra.

Keywords tal-schema

parameters (input_schema fuq /v1/messages) huwa JSON Schema. Il-familja Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) u l-mudelli open-weight ospitati jirċevuh kif tibgħatu.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro u shannon-coder-1 jirċievu dan is-sottoinsieme, fit-tliet endpoints kollha:

Trattament Keywords
Jinqara kif intbagħat Kull keyword li ma tissemmiex fir-ringieli hawn taħt, pereżempju type, properties, required, items, enum, description, minimum, maximum, anyOf u allOf, f'kull livell tal-schema.
format Jinqara għall-valuri int32, int64, float, double, byte, date, date-time u enum.
oneOf Jinqara bħala anyOf.
Mhux parti mill-schema li jirċievu dawn il-mudelli $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 u exclusiveMaximum meta jkunu numri; valuri oħra ta' format.

Imġiba u limiti

  • L-API ma tistabbilixxi l-ebda numru massimu ta' tools u l-ebda numru massimu ta' rounds.
  • Body ta' talba jista' jkun sa 32 MiB, u l-konversazzjoni bir-riżultati tagħha trid tidħol fit-tieqa tal-kuntest tal-mudell.
  • Meta talba ġġorr tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite u shannon-2-pro jużaw temperature default ta' 0.2. Ibgħat temperature biex tistabbilixxi valur ieħor.
  • Kull round huwa talba waħedha: tieħu mill-bilanċ tiegħek u tingħadd għall-protezzjoni mill-flood bħal kull talba oħra. Limiti u bilanċ

Żbalji

Sejħa ta' tool hija tweġiba normali b'status 200. Dawn l-iżbalji jirrigwardaw it-talba nnifisha:

Status Tip Messaġġ Meta
400 invalid_request_error unknown model: <id> model mhuwiex id mil-lista ppubblikata.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools mhuwiex array, jew qasam ieħor għandu tip JSON ħażin.
413 invalid_request_error Failed to buffer the request body: … Il-body tat-talba huwa akbar minn 32 MiB. L-iżball iġorr code: "request_too_large".

Il-mudell jikteb l-argumenti. Iċċekkjahom mal-schema tiegħek qabel tħaddem il-funzjoni, bħalma tiċċekkja kwalunkwe input minn barra.

L-iżbalji ta' awtentikazzjoni, bilanċ u server huma l-istess bħal għal kull talba. Ġestjoni tal-iżbalji