Kalo te përmbajtja
Thirrje funksionesh

Thirrje funksionesh

Përshkruani funksionet tuaja në kërkesë dhe modeli përgjigjet me thirrjet që dëshiron të bëhen. Kodi juaj i ekzekuton dhe dërgon rezultatet mbrapsht: API-ja kthen thirrje mjetesh dhe vetë nuk ekzekuton asnjë mjet.

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

Shembujt në këtë faqe përdorin /v1/chat/completions. I njëjti cikël funksionon në /v1/responses dhe /v1/messages; ku një format e shkruan diçka ndryshe, seksionet më poshtë i tregojnë të tri.

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)

Përgjigjja e parë nuk i përgjigjet pyetjes. Kërkon një thirrje:

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

Pasi dërgoni rezultatin, përgjigjja tjetër është një përgjigje e zakonshme: message.content mban tekstin dhe finish_reason është stop.

Cikli, hap pas hapi

Hapi Kush Çfarë ndodh
1 Ju Dërgoni messages së bashku me tools, listën e funksioneve që modeli mund të kërkojë.
2 Modeli Përgjigjja mban tool_calls dhe finish_reason: "tool_calls". Çdo thirrje emërton një funksion dhe jep argumentet e tij.
3 Ju Parsoni arguments e çdo thirrjeje dhe ekzekutoni funksionin tuaj.
4 Ju Shtoni te messages mesazhin e assistant dhe një mesazh tool për çdo thirrje, pastaj dërgojeni kërkesën përsëri me të njëjtat tools.
5 Modeli Modeli përgjigjet me tekst me finish_reason: "stop", ose kërkon thirrje të tjera. Në atë rast kthehuni te hapi 3.

Një kërkesë është një radhë e modelit. API-ja nuk mban bisedë mes kërkesave dhe nuk cakton numër raundesh: kodi juaj mban messages dhe vendos kur të ndalojë.

Përcaktimi i mjeteve

tools është një varg me një hyrje për funksion. Çdo model i katalogut e pranon; GET /v1/models raporton capabilities.tools: true për çdo id.

Fusha Lloji Përshkrimi
type string Gjithmonë function.
function.name string Emri që përdor modeli kur kërkon këtë funksion. I detyrueshëm.
function.description string Çfarë bën funksioni, në gjuhë të thjeshtë.
function.parameters object Argumentet si JSON Schema me type: "object" në krye. Shihni Fjalët kyçe të skemës më poshtë.

Çdo endpoint ka shkrimin e vet të një mjeti. Dërgoni atë që i përket endpoint-it që thërrisni:

{
  "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 thotë nëse modeli mund ose duhet të thërrasë një mjet. Lexohet vetëm së bashku me tools.

Vlera Përshkrimi Zbatohet nga
"auto" Modeli vendos nëse do të përgjigjet me tekst ose do të thërrasë një mjet. Kjo është parazgjedhja. Të gjitha modelet
"required" Përgjigjja thërret të paktën një mjet. Modele open-weight të hostuara
{"type": "function", "function": {"name": "get_weather"}} Përgjigjja thërret këtë funksion. Emri duhet të jetë një nga funksionet te tools. Thirrjet e funksioneve të tjera lihen jashtë përgjigjes. Modele open-weight të hostuara

Modelet Shannon (shannon-*) vendosin në çdo kërkesë, si me auto.

Me required ose një funksion të emërtuar, lexoni finish_reason para se të lexoni tool_calls. Kur modeli nuk prodhon thirrje, përgjigjja është një përgjigje teksti me finish_reason: "stop".

Kuptimi /v1/chat/completions /v1/responses /v1/messages
Modeli vendos "auto" "auto" {"type": "auto"}
Thirr të paktën një mjet "required" "required" {"type": "any"}
Thirr një funksion të emërtuar {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Pranohen për pajtueshmëri: tool_choice: "none" dhe parallel_tool_calls. Për një radhë pa thirrje mjetesh, dërgojeni kërkesën pa tools.

Thirrjet e mjeteve në përgjigje

Fusha Lloji Përshkrimi
finish_reason string tool_calls kur përgjigjja mban të paktën një thirrje.
message.tool_calls array Një hyrje për thirrje. Fusha është e pranishme vetëm kur modeli ka kërkuar një thirrje.
tool_calls[].id string call_ e ndjekur nga 32 karaktere heksadecimale. Dërgojeni mbrapsht si tool_call_id me rezultatin.
tool_calls[].type string Gjithmonë function.
tool_calls[].function.name string Funksioni që do të ekzekutohet.
tool_calls[].function.arguments string Argumentet si string JSON, "{}" kur nuk ka. Parsoni para përdorimit.
message.content string | null null kur përgjigjja mban vetëm thirrje. Modelet open-weight të hostuara mund të kthejnë tekst pranë thirrjeve; modelet Shannon kthejnë null.

E njëjta thirrje në çdo format. Në /v1/responses është një element function_call i output, me arguments si string JSON. Në /v1/messages është një bllok përmbajtjeje tool_use ku input është objekt JSON, id fillon me toolu_, dhe stop_reason është 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\"}"
        }
      }
    ]
  }
}

Disa thirrje në një radhë

Një përgjigje mund të mbajë disa thirrje. Ekzekutoni të gjitha dhe dërgoni një rezultat për thirrje, secili me tool_call_id të vet, në kërkesën tjetër.

Modelet open-weight të hostuara e kthejnë çdo thirrje të veçantë një herë: dy thirrje me të njëjtin emër dhe të njëjtat argumente arrijnë si një.

Thirrje mjetesh me stream

Me stream: true, një thirrje arrin në një copë të vetme: pjesa mban stringun e plotë arguments, kështu që nuk ka fragmente për t'u bashkuar. index i numëron thirrjet e radhës nga 0.

data: një pjesë, e formatuar
{
  "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 Çfarë arrin
/v1/chat/completions Një chat.completion.chunk për thirrje, me thirrjen te delta.tool_calls[0]. Pjesa e fundit ka finish_reason: "tool_calls" dhe usage.
/v1/responses Për thirrje: response.output_item.added (një element function_call me arguments bosh), response.function_call_arguments.delta (i gjithë stringu), response.function_call_arguments.done, response.output_item.done.
/v1/messages Për thirrje: content_block_start (një bllok tool_use me input bosh), një content_block_delta ku input_json_delta.partial_json është i gjithë teksti i argumenteve, content_block_stop. Pastaj message_delta mban stop_reason: "tool_use".

Te shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro dhe shannon-coder-1, një kërkesë me stream që mban tools e jep tekstin e përgjigjes në një delta content në fund të radhës. Transmetim

Dërgimi i rezultateve mbrapsht

Kërkesa e dytë e përsërit bisedën dhe shton dy gjëra: radhën e assistant që kërkoi thirrjet, dhe një rezultat për çdo thirrje.

{
  "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\"}"
    }
  ]
}
  • Dërgojeni radhën e assistant mbrapsht siç e morët, para rezultateve. Çdo rezultat lidhet me thirrjen e vet sipas id-së: tool_call_id në /v1/chat/completions, call_id në /v1/responses, tool_use_id në /v1/messages.
  • Një rezultat është tekst. Serializojeni një objekt në string JSON për content (output në /v1/responses). Në /v1/messages content i një blloku tool_result është string ose listë blloqesh teksti.
  • Në radhën e assistant, function.arguments mbetet string JSON, saktësisht siç arriti.
  • Biseda mund të mbarojë me një rezultat mjeti. Nuk nevojitet mesazh i ri përdoruesi: modeli vazhdon nga rezultati.
  • Kur funksioni juaj dështon, dërgojeni dështimin si tekst rezultati. Modeli pastaj mund ta raportojë ose të kërkojë një thirrje tjetër.

Fjalët kyçe të skemës

parameters (input_schema në /v1/messages) është një JSON Schema. Familja Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) dhe modelet open-weight të hostuara e marrin siç e dërgoni.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro dhe shannon-coder-1 e marrin këtë nëngrup, në të tri endpoint-et:

Trajtimi Fjalët kyçe
Lexohet siç dërgohet Çdo fjalë kyçe që nuk emërtohet në rreshtat më poshtë, për shembull type, properties, required, items, enum, description, minimum, maximum, anyOf dhe allOf, në çdo nivel të skemës.
format Lexohet për vlerat int32, int64, float, double, byte, date, date-time dhe enum.
oneOf Lexohet si anyOf.
Nuk është pjesë e skemës që marrin këta modele $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 dhe exclusiveMaximum kur janë numra; vlera të tjera të format.

Sjellja dhe kufijtë

  • API-ja nuk cakton numër maksimal mjetesh dhe as numër maksimal raundesh.
  • Trupi i një kërkese mund të jetë deri në 32 MiB, dhe biseda me rezultatet e saj duhet të ngjitet në dritaren e kontekstit të modelit.
  • Kur një kërkesë mban tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite dhe shannon-2-pro përdorin një temperature të parazgjedhur 0.2. Dërgoni temperature për të caktuar vlerë tjetër.
  • Çdo raund është kërkesë më vete: tërheq nga bilanci juaj dhe numërohet te mbrojtja nga vërshimi i kërkesave si çdo kërkesë tjetër. Kufijtë dhe bilanci

Gabimet

Një thirrje mjeti është një përgjigje normale me status 200. Këto gabime lidhen me vetë kërkesën:

Statusi Lloji Mesazhi Kur
400 invalid_request_error unknown model: <id> model nuk është id e listës së publikuar.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools nuk është varg, ose një fushë tjetër ka lloj JSON të gabuar.
413 invalid_request_error Failed to buffer the request body: … Trupi i kërkesës është më i madh se 32 MiB. Gabimi mban code: "request_too_large".

Argumentet i shkruan modeli. Kontrolloni ato kundrejt skemës suaj para se ta ekzekutoni funksionin, siç do të kontrollonit çdo hyrje nga jashtë.

Gabimet e autentikimit, bilancit dhe serverit janë të njëjta si për çdo kërkesë. Trajtimi i gabimeve