Pereiti prie turinio
Funkcijų kvietimas

Funkcijų kvietimas

Apibūdinkite savo funkcijas užklausoje, o modelis atsakys kreipiniais, kuriuos nori atlikti. Jūsų kodas juos vykdo ir grąžina rezultatus: API grąžina įrankių kreipinius ir pats įrankio nevykdo.

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

Šio puslapio pavyzdžiuose naudojamas /v1/chat/completions. Tas pats ciklas veikia kelyje /v1/responses ir /v1/messages; kur formatai kažką užrašo kitaip, toliau pateikiami visi trys variantai.

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)

Pirmasis atsakymas į klausimą neatsako. Jame prašoma kreipinio:

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

Išsiuntus rezultatą, kitas atsakymas yra įprastas atsakymas: message.content talpina tekstą, o finish_reason yra stop.

Ciklas žingsnis po žingsnio

Žingsnis Kas Kas vyksta
1 Jūs Siųskite messages kartu su tools – funkcijų, kurių modelis gali prašyti, sąrašu.
2 Modelis Atsakyme yra tool_calls ir finish_reason: "tool_calls". Kiekvienas kreipinys nurodo funkciją ir pateikia jos argumentus.
3 Jūs Išanalizuokite kiekvieno kreipinio arguments ir vykdykite savo funkciją.
4 Jūs Prie messages pridėkite asistento pranešimą ir po vieną tool pranešimą kiekvienam kreipiniui, tada vėl siųskite užklausą su tais pačiais tools.
5 Modelis Modelis atsako tekstu su finish_reason: "stop" arba prašo daugiau kreipinių. Tuo atveju grįžkite prie 3 žingsnio.

Viena užklausa yra vienas modelio ėjimas. API tarp užklausų pokalbio nesaugo ir ratų skaičiaus nenustato: messages laikote jūs ir jūs nusprendžiate, kada sustoti.

Įrankių apibrėžimas

tools yra masyvas, kuriame po vieną įrašą kiekvienai funkcijai. Jį priima kiekvienas katalogo modelis; GET /v1/models kiekvienam id nurodo capabilities.tools: true.

Laukas Tipas Aprašymas
type string Visada function.
function.name string Pavadinimas, kurį modelis naudoja prašydamas šios funkcijos. Privalomas.
function.description string Ką funkcija daro, paprasta kalba.
function.parameters object Argumentai kaip JSON Schema, viršuje su type: "object". Žr. toliau Schemos raktažodžiai.

Kiekvienas galinis taškas turi savo įrankio užrašymo būdą. Siųskite tą, kuris priklauso jūsų kviečiamam galiniam taškui:

{
  "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 nurodo, ar modelis gali, ar privalo iškviesti įrankį. Jis skaitomas tik kartu su tools.

Reikšmė Aprašymas Taiko
"auto" Modelis pats nusprendžia, ar atsakyti tekstu, ar iškviesti įrankį. Tai numatytoji reikšmė. Visi modeliai
"required" Atsakyme kviečiamas bent vienas įrankis. Talpinami atvirų svorių modeliai
{"type": "function", "function": {"name": "get_weather"}} Atsakyme kviečiama ši funkcija. Pavadinimas turi būti viena iš tools funkcijų. Kreipiniai į kitas funkcijas iš atsakymo pašalinami. Talpinami atvirų svorių modeliai

Shannon modeliai (shannon-*) sprendžia kiekvienoje užklausoje, kaip ir su auto.

Naudodami required arba įvardytą funkciją, prieš skaitydami tool_calls perskaitykite finish_reason. Kai modelis kreipinio nesukuria, atsakymas yra tekstinis su finish_reason: "stop".

Reikšmė /v1/chat/completions /v1/responses /v1/messages
Modelis sprendžia pats "auto" "auto" {"type": "auto"}
Iškviesti bent vieną įrankį "required" "required" {"type": "any"}
Iškviesti vieną įvardytą funkciją {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Dėl suderinamumo priimami: tool_choice: "none" ir parallel_tool_calls. Jei ėjimui kreipinių nereikia, siųskite užklausą be tools.

Įrankių kreipiniai atsakyme

Laukas Tipas Aprašymas
finish_reason string tool_calls, kai atsakyme yra bent vienas kreipinys.
message.tool_calls array Vienas įrašas kiekvienam kreipiniui. Laukas yra tik tada, kai modelis paprašė kreipinio.
tool_calls[].id string call_ ir 32 šešioliktainiai simboliai. Siųsdami rezultatą, grąžinkite jį kaip tool_call_id.
tool_calls[].type string Visada function.
tool_calls[].function.name string Vykdytina funkcija.
tool_calls[].function.arguments string Argumentai kaip JSON eilutė, "{}", jei jų nėra. Prieš naudodami ją išanalizuokite.
message.content string | null null, kai atsakyme yra tik kreipiniai. Talpinami atvirų svorių modeliai gali grąžinti tekstą šalia kreipinių; Shannon modeliai grąžina null.

Tas pats kreipinys kiekvienu formatu. Kelyje /v1/responses tai output elementas function_call, kurio arguments yra JSON eilutė. Kelyje /v1/messages tai turinio blokas tool_use, kurio input yra JSON objektas, id prasideda toolu_, o stop_reason yra 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\"}"
        }
      }
    ]
  }
}

Keli kreipiniai viename ėjime

Atsakyme gali būti keli kreipiniai. Vykdykite visus ir kitoje užklausoje siųskite po vieną rezultatą kiekvienam kreipiniui, kiekvieną su savo tool_call_id.

Talpinami atvirų svorių modeliai kiekvieną skirtingą kreipinį grąžina vieną kartą: du kreipiniai su tuo pačiu pavadinimu ir tais pačiais argumentais ateina kaip vienas.

Srautiniai įrankių kreipiniai

Su stream: true kreipinys ateina vienu gabalu: gabale yra visa arguments eilutė, todėl nėra fragmentų, kuriuos reikėtų jungti. index skaičiuoja ėjimo kreipinius nuo 0.

data: vienas gabalas, suformatuotas
{
  "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
    }
  ]
}
Galinis taškas Kas gaunama
/v1/chat/completions Vienas chat.completion.chunk kiekvienam kreipiniui, kreipinys yra delta.tool_calls[0]. Paskutiniame gabale yra finish_reason: "tool_calls" ir usage.
/v1/responses Kiekvienam kreipiniui: response.output_item.added (function_call elementas su tuščiu arguments), response.function_call_arguments.delta (visa eilutė), response.function_call_arguments.done, response.output_item.done.
/v1/messages Kiekvienam kreipiniui: content_block_start (tool_use blokas su tuščiu input), vienas content_block_delta, kurio input_json_delta.partial_json yra visas argumentų tekstas, content_block_stop. Tada message_delta turi stop_reason: "tool_use".

Su shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ir shannon-coder-1 srautinė užklausa su tools pateikia atsakymo tekstą vienu content delta ėjimo pabaigoje. Srautinė transliacija

Rezultatų grąžinimas

Antroji užklausa pakartoja pokalbį ir prideda du dalykus: asistento ėjimą, kuriame prašyta kreipinių, ir po vieną rezultatą kiekvienam kreipiniui.

{
  "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\"}"
    }
  ]
}
  • Prieš rezultatus grąžinkite asistento ėjimą tokį, kokį gavote. Kiekvienas rezultatas su kreipiniu susiejamas pagal id: tool_call_id kelyje /v1/chat/completions, call_id kelyje /v1/responses, tool_use_id kelyje /v1/messages.
  • Rezultatas yra tekstas. Objektą paverskite JSON eilute ir įrašykite į content (output kelyje /v1/responses). Kelyje /v1/messages bloko tool_result content yra eilutė arba tekstinių blokų sąrašas.
  • Asistento ėjime function.arguments lieka JSON eilute, lygiai tokia, kokia atėjo.
  • Pokalbis gali baigtis įrankio rezultatu. Naujo naudotojo pranešimo nereikia: modelis tęsia nuo rezultato.
  • Kai jūsų funkcija nepavyksta, klaidą siųskite kaip rezultato tekstą. Tada modelis gali apie ją pranešti arba paprašyti kito kreipinio.

Schemos raktažodžiai

parameters (input_schema kelyje /v1/messages) yra JSON Schema. Shannon 3 šeima (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ir talpinami atvirų svorių modeliai gauna ją tokią, kokią siunčiate.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ir shannon-coder-1 gauna šį poaibį visuose trijuose galiniuose taškuose:

Apdorojimas Raktažodžiai
Skaitoma taip, kaip išsiųsta Kiekvienas raktažodis, kuris nepaminėtas toliau esančiose eilutėse, pavyzdžiui, type, properties, required, items, enum, description, minimum, maximum, anyOf ir allOf, visuose schemos lygiuose.
format Skaitoma reikšmėms int32, int64, float, double, byte, date, date-time ir enum.
oneOf Skaitoma kaip anyOf.
Nepatenka į schemą, kurią gauna šie modeliai $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 ir exclusiveMaximum, kai jie yra skaičiai; kitos format reikšmės.

Elgsena ir apribojimai

  • API nenustato didžiausio įrankių skaičiaus ir didžiausio ratų skaičiaus.
  • Užklausos turinys gali siekti 32 MiB, o pokalbis su rezultatais turi tilpti į modelio konteksto langą.
  • Kai užklausoje yra tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ir shannon-2-pro naudoja numatytąją temperature reikšmę 0.2. Kitai reikšmei nustatyti siųskite temperature.
  • Kiekvienas ratas yra atskira užklausa: ji nuskaičiuojama nuo jūsų balanso ir, kaip ir kitos užklausos, įskaičiuojama į apsaugą nuo užplūdimo. Ribos ir balansas

Klaidos

Įrankio kreipinys yra įprastas atsakymas su būsena 200. Šios klaidos susijusios su pačia užklausa:

Būsena Tipas Pranešimas Kada
400 invalid_request_error unknown model: <id> model nėra paskelbto sąrašo id.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools nėra masyvas arba kitas laukas turi netinkamą JSON tipą.
413 invalid_request_error Failed to buffer the request body: … Užklausos turinys didesnis nei 32 MiB. Klaidoje yra code: "request_too_large".

Argumentus rašo modelis. Prieš vykdydami funkciją patikrinkite juos pagal savo schemą, kaip tikrintumėte bet kokius išorinius duomenis.

Autentifikavimo, balanso ir serverio klaidos tokios pačios kaip ir kiekvienai užklausai. Klaidų tvarkymas