Mine sisu juurde
Funktsioonikutse

Funktsioonikutse

Kirjelda oma funktsioonid päringus ja mudel vastab kutsetega, mida ta soovib teha. Sinu kood käivitab need ja saadab tulemused tagasi: API tagastab tööriistakutsed ega käivita tööriista ise.

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

Selle lehe näited kasutavad /v1/chat/completions. Sama tsükkel töötab lõpp-punktides /v1/responses ja /v1/messages; kus formaat kirjutab midagi teisiti, näitavad allolevad jaotised kõiki kolme.

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)

Esimene vastus ei vasta küsimusele. See küsib kutset:

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

Pärast tulemuse saatmist on järgmine vastus tavaline vastus: message.content sisaldab teksti ja finish_reason on stop.

Tsükkel samm-sammult

Samm Kes Mis juhtub
1 Sina Saada messages koos tools-ga, funktsioonide loendiga, mida mudel võib küsida.
2 Mudel Vastus kannab tool_calls ja finish_reason: "tool_calls". Iga kutse nimetab funktsiooni ja annab selle argumendid.
3 Sina Parsi iga kutse arguments ja käivita oma funktsioon.
4 Sina Lisa assistendi sõnum ja üks tool-sõnum kutse kohta väljale messages, seejärel saada päring uuesti sama tools-ga.
5 Mudel Mudel vastab tekstiga väärtusega finish_reason: "stop" või küsib veel kutseid. Sel juhul mine tagasi sammu 3 juurde.

Üks päring on üks mudeli vahetus. API ei hoia päringute vahel vestlust ega sea voorude arvu: sinu kood hoiab messages ja otsustab, millal peatuda.

Tööriistade defineerimine

tools on massiiv, milles on üks kirje funktsiooni kohta. Iga kataloogi mudel võtab seda vastu; GET /v1/models teatab iga id kohta capabilities.tools: true.

Väli Tüüp Kirjeldus
type string Alati function.
function.name string Nimi, mida mudel kasutab, kui ta seda funktsiooni küsib. Nõutav.
function.description string Mida funktsioon teeb, lihtsas keeles.
function.parameters object Argumendid JSON Schemana, mille tipus on type: "object". Vaata allpool Skeemi märksõnad.

Igal lõpp-punktil on tööriista jaoks oma kirjaviis. Saada see, mis kuulub lõpp-punktile, mida kutsud:

{
  "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 ütleb, kas mudel võib või peab tööriista kutsuma. Seda loetakse ainult koos tools.

Väärtus Kirjeldus Rakendavad
"auto" Mudel otsustab, kas vastata tekstiga või kutsuda tööriista. See on vaikeväärtus. Kõik mudelid
"required" Vastus kutsub vähemalt ühte tööriista. Hostitud avatud kaaludega mudelid
{"type": "function", "function": {"name": "get_weather"}} Vastus kutsub seda funktsiooni. Nimi peab olema üks tools funktsioonidest. Kutsed teistele funktsioonidele jäetakse vastusest välja. Hostitud avatud kaaludega mudelid

Shannoni mudelid (shannon-*) otsustavad igas päringus ise, nagu väärtusega auto.

Väärtuse required või nimetatud funktsiooni puhul loe finish_reason enne, kui loed tool_calls. Kui mudel kutset ei tee, on vastus tekstivastus väärtusega finish_reason: "stop".

Tähendus /v1/chat/completions /v1/responses /v1/messages
Mudel otsustab "auto" "auto" {"type": "auto"}
Kutsu vähemalt ühte tööriista "required" "required" {"type": "any"}
Kutsu üht nimetatud funktsiooni {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Võetakse ühilduvuse tarbeks vastu: tool_choice: "none" ja parallel_tool_calls. Vahetuse jaoks ilma tööriistakutseteta saada päring ilma tools.

Tööriistakutsed vastuses

Väli Tüüp Kirjeldus
finish_reason string tool_calls, kui vastus kannab vähemalt ühte kutset.
message.tool_calls array Üks kirje kutse kohta. Väli on olemas ainult siis, kui mudel küsis kutset.
tool_calls[].id string call_, millele järgneb 32 kuueteistkümnendsüsteemi märki. Saada see tulemusega tagasi kui tool_call_id.
tool_calls[].type string Alati function.
tool_calls[].function.name string Funktsioon, mida käivitada.
tool_calls[].function.arguments string Argumendid JSON-stringina, "{}", kui neid ei ole. Parsi see enne kasutamist.
message.content string | null null, kui vastus sisaldab ainult kutseid. Hostitud avatud kaaludega mudelid võivad kutsete kõrval tagastada teksti; Shannoni mudelid tagastavad null.

Sama kutse igas formaadis. Lõpp-punktis /v1/responses on see output üksus function_call, kus arguments on JSON-string. Lõpp-punktis /v1/messages on see tool_use sisuplokk, mille input on JSON-objekt, selle id algab toolu_ ja stop_reason on 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\"}"
        }
      }
    ]
  }
}

Mitu kutset ühes vahetuses

Vastus võib kanda mitut kutset. Käivita igaüks neist ja saada järgmises päringus üks tulemus kutse kohta, igaühel oma tool_call_id.

Hostitud avatud kaaludega mudelid tagastavad iga erineva kutse ühe korra: kaks sama nime ja samade argumentidega kutset saabuvad ühena.

Voogedastatud tööriistakutsed

Väärtusega stream: true saabub kutse tervikuna: chunk sisaldab täielikku arguments stringi, seega ei ole katkeid, mida ühendada. index loeb vahetuse kutseid alates 0.

data: üks chunk, vormindatud
{
  "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
    }
  ]
}
Lõpp-punkt Mis saabub
/v1/chat/completions Üks chat.completion.chunk kutse kohta, kutsega väljal delta.tool_calls[0]. Viimasel chunkil on finish_reason: "tool_calls" ja usage.
/v1/responses Kutse kohta: response.output_item.added (function_call üksus tühja arguments-iga), response.function_call_arguments.delta (kogu string), response.function_call_arguments.done, response.output_item.done.
/v1/messages Kutse kohta: content_block_start (tool_use-plokk tühja input-iga), üks content_block_delta, mille input_json_delta.partial_json on kogu argumentide tekst, content_block_stop. Seejärel kannab message_delta väärtust stop_reason: "tool_use".

Mudelitel shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ja shannon-coder-1 annab voogedastatud päring, mis kannab tools, oma vastuse teksti ühes content deltas vahetuse lõpus. Voogedastus

Tulemuste tagasi saatmine

Teine päring kordab vestlust ja lisab kaks asja: assistendi vahetuse, mis küsis kutseid, ja ühe tulemuse kutse kohta.

{
  "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\"}"
    }
  ]
}
  • Saada assistendi vahetus tagasi nii, nagu selle said, enne tulemusi. Iga tulemus seotakse oma kutsega id järgi: tool_call_id lõpp-punktis /v1/chat/completions, call_id lõpp-punktis /v1/responses, tool_use_id lõpp-punktis /v1/messages.
  • Tulemus on tekst. Serialiseeri objekt JSON-stringiks väljale content (output lõpp-punktis /v1/responses). Lõpp-punktis /v1/messages on tool_result ploki content string või tekstiplokkide loend.
  • Assistendi vahetuses jääb function.arguments JSON-stringiks, täpselt nii, nagu see saabus.
  • Vestlus võib lõppeda tööriista tulemusega. Uut kasutaja sõnumit ei ole vaja: mudel jätkab tulemusest.
  • Kui sinu funktsioon ebaõnnestub, saada tõrge tulemuse tekstina. Mudel saab siis sellest teatada või küsida teist kutset.

Skeemi märksõnad

parameters (input_schema lõpp-punktis /v1/messages) on JSON Schema. Shannon 3 perekond (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ja hostitud avatud kaaludega mudelid saavad selle nii, nagu sa selle saadad.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ja shannon-coder-1 saavad selle alamhulga, kõigis kolmes lõpp-punktis:

Käsitlus Märksõnad
Loetakse nii, nagu saadeti Iga märksõna, mida allolevates ridades ei nimetata, näiteks type, properties, required, items, enum, description, minimum, maximum, anyOf ja allOf, skeemi igal tasandil.
format Loetakse väärtuste int32, int64, float, double, byte, date, date-time ja enum jaoks.
oneOf Loetakse kui anyOf.
Ei kuulu skeemi, mille need mudelid saavad $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 ja exclusiveMaximum, kui need on arvud; format muud väärtused.

Käitumine ja piirangud

  • API ei sea tööriistade arvule ega voorude arvule ülempiiri.
  • Päringu sisu võib olla kuni 32 MiB ning vestlus koos tulemustega peab mahtuma mudeli kontekstiaknasse.
  • Kui päring kannab tools, kasutavad shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ja shannon-2-pro vaike-temperature väärtust 0.2. Saada temperature, et määrata muu väärtus.
  • Iga voor on eraldi päring: see võtab sinu saldost ja loeb kiirusepiirangusse nagu iga teine päring. Piirangud ja saldo

Vead

Tööriistakutse on tavaline vastus olekuga 200. Need vead puudutavad päringut ennast:

Olek Tüüp Teade Millal
400 invalid_request_error unknown model: <id> model ei ole avaldatud loendi id.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools ei ole massiiv või mõnel muul väljal on vale JSON-tüüp.
413 invalid_request_error Failed to buffer the request body: … Päringu sisu on suurem kui 32 MiB. Viga kannab code: "request_too_large".

Argumendid kirjutab mudel. Kontrolli neid oma skeemi vastu enne funktsiooni käivitamist, nagu kontrolliksid mis tahes välist sisendit.

Autentimise, saldo ja serveri vead on samad mis igal päringul. Vigade käsitlus