Joan edukira
Funtzio-deiak

Funtzio-deiak

Deskribatu zure funtzioak eskaeran eta modeloak egin nahi dituen deiekin erantzungo du. Zure kodeak exekutatzen ditu eta emaitzak bidaltzen ditu berriro: API-ak tresna-deiak itzultzen ditu eta ez du tresnarik berak exekutatzen.

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

Orrialde honetako laginek /v1/chat/completions erabiltzen dute. Begizta bera /v1/responses eta /v1/messages endpoint-etan ere exekutatzen da; formatu batek zerbait modu desberdinean idazten duenean, beheko ataletan hiru formak erakusten dira.

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)

Lehen erantzunak ez du galderari erantzuten. Dei bat eskatzen du:

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

Emaitza bidali ondoren, hurrengo erantzuna ohiko erantzun bat da: message.content-ek testua du eta finish_reason stop da.

Begizta, urratsez urrats

Urratsa Nork Zer gertatzen den
1 Zuk Bidali messages eta tools batera, modeloak eska ditzakeen funtzioen zerrenda.
2 Modeloa Erantzunak tool_calls eta finish_reason: "tool_calls" ditu. Dei bakoitzak funtzio bat izendatzen du eta bere argumentuak ematen ditu.
3 Zuk Aztertu dei bakoitzaren arguments eta exekutatu zure funtzioa.
4 Zuk Gehitu assistant mezua eta tool mezu bat dei bakoitzeko messages-era, eta bidali eskaera berriro tools berberekin.
5 Modeloa Modeloak testuan erantzuten du finish_reason: "stop" erabiliz, edo dei gehiago eskatzen ditu. Kasu horretan itzuli 3. urratsera.

Eskaera bat modelo-txanda bat da. API-ak ez du elkarrizketarik gordetzen eskaeren artean eta ez du itzuli-kopururik ezartzen: zure kodeak messages gordetzen du eta noiz gelditu erabakitzen du.

Tresnak definitzea

tools array bat da, funtzio bakoitzeko sarrera batekin. Katalogoko modelo guztiek onartzen dute; GET /v1/models-ek capabilities.tools: true jakinarazten du id guztientzat.

Eremua Mota Deskribapena
type string Beti function.
function.name string Modeloak funtzio hau eskatzean erabiltzen duen izena. Beharrezkoa.
function.description string Funtzioak zer egiten duen, hizkuntza arruntean.
function.parameters object Argumentuak JSON Schema gisa, goian type: "object" duela. Ikus beheko Eskema-gako-hitzak.

Endpoint bakoitzak bere idazkera du tresna baterako. Bidali deitzen duzun endpoint-ari dagokiona:

{
  "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-k esaten du modeloak tresna bati dei diezaiokeen edo deitu behar duen. tools-ekin batera bakarrik irakurtzen da.

Balioa Deskribapena Aplikatzen duena
"auto" Modeloak erabakitzen du testuan erantzun ala tresna bati deitu. Hau da lehenetsia. Modelo guztiak
"required" Erantzunak tresna bati gutxienez deitzen dio. Pisu irekiko modelo ostatatuak
{"type": "function", "function": {"name": "get_weather"}} Erantzunak funtzio horri deitzen dio. Izenak tools-eko funtzioetako bat izan behar du. Beste funtzioei egindako deiak erantzunetik kanpo uzten dira. Pisu irekiko modelo ostatatuak

Shannon modeloek (shannon-*) eskaera bakoitzean erabakitzen dute, auto bezala.

required edo izendatutako funtzio batekin, irakurri finish_reason tool_calls irakurri aurretik. Modeloak deirik sortzen ez duenean, erantzuna testu-erantzun bat da, finish_reason: "stop" duena.

Esanahia /v1/chat/completions /v1/responses /v1/messages
Modeloak erabakitzen du "auto" "auto" {"type": "auto"}
Tresna bati gutxienez deitu "required" "required" {"type": "any"}
Funtzio izendatu bati deitu {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Bateragarritasunerako onartuak: tool_choice: "none" eta parallel_tool_calls. Tresna-deirik gabeko txanda baterako, bidali eskaera tools gabe.

Tresna-deiak erantzunean

Eremua Mota Deskribapena
finish_reason string tool_calls erantzunak dei bat gutxienez daramanean.
message.tool_calls array Sarrera bat dei bakoitzeko. Eremua modeloak dei bat eskatu duenean bakarrik dago.
tool_calls[].id string call_ eta ondoren 32 karaktere hexadezimal. Bidali berriro tool_call_id gisa emaitzarekin.
tool_calls[].type string Beti function.
tool_calls[].function.name string Exekutatu beharreko funtzioa.
tool_calls[].function.arguments string Argumentuak JSON kate gisa, "{}" batere ez dagoenean. Aztertu erabili aurretik.
message.content string | null null erantzunak deiak bakarrik dituenean. Pisu irekiko modelo ostatatuek testua itzul dezakete deien ondoan; Shannon modeloek null itzultzen dute.

Dei bera formatu bakoitzean. /v1/responses endpoint-ean output-eko function_call elementu bat da, arguments JSON kate gisa duela. /v1/messages endpoint-ean tool_use eduki-bloke bat da, bere input JSON objektu bat dela, bere id toolu_ hasten dela, eta stop_reason tool_use dela.

{
  "finish_reason": "tool_calls",
  "message": {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Paris\"}"
        }
      }
    ]
  }
}

Dei anitz txanda batean

Erantzun batek dei anitz eraman ditzake. Exekutatu guztiak eta bidali emaitza bat dei bakoitzeko, bakoitza bere tool_call_id-rekin, hurrengo eskaeran.

Pisu irekiko modelo ostatatuek dei bereizi bakoitza behin itzultzen dute: izen bera eta argumentu berak dituzten bi dei bat bezala iristen dira.

Stream bidezko tresna-deiak

stream: true erabiliz, dei bat zati bakarrean iristen da: chunk-ak arguments kate osoa du, beraz ez dago elkartzeko zatirik. index-ek txandako deiak 0tik kontatzen ditu.

data: chunk bat, formateatua
{
  "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-a Zer iristen den
/v1/chat/completions chat.completion.chunk bat dei bakoitzeko, deia delta.tool_calls[0]-n dela. Azken chunk-ak finish_reason: "tool_calls" eta usage ditu.
/v1/responses Dei bakoitzeko: response.output_item.added (function_call elementu bat arguments hutsarekin), response.function_call_arguments.delta (kate osoa), response.function_call_arguments.done, response.output_item.done.
/v1/messages Dei bakoitzeko: content_block_start (tool_use bloke bat input hutsarekin), content_block_delta bat non input_json_delta.partial_json argumentuen testu osoa den, content_block_stop. message_delta-k orduan stop_reason: "tool_use" darama.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro eta shannon-coder-1 modeloetan, tools darabilen stream bidezko eskaerak bere erantzun-testua content delta batean ematen du txandaren amaieran. Streaminga

Emaitzak berriro bidaltzea

Bigarren eskaerak elkarrizketa errepikatzen du eta bi gauza gehitzen ditu: deiak eskatu zituen assistant txanda, eta emaitza bat dei bakoitzeko.

{
  "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\"}"
    }
  ]
}
  • Bidali assistant txanda berriro jaso zenuen bezala, emaitzen aurretik. Emaitza bakoitza bere deiarekin id bidez lotzen da: tool_call_id /v1/chat/completions endpoint-ean, call_id /v1/responses endpoint-ean, tool_use_id /v1/messages endpoint-ean.
  • Emaitza testu bat da. Serializatu objektu bat JSON kate batera content-erako (output /v1/responses endpoint-ean). /v1/messages endpoint-ean tool_result bloke baten content kate bat da edo testu-blokeen zerrenda bat.
  • Assistant txandan, function.arguments JSON kate izaten jarraitzen du, iritsi zen bezala.
  • Elkarrizketa tresna-emaitza batekin amaitu daiteke. Ez da erabiltzaile-mezu berririk behar: modeloak emaitzatik jarraitzen du.
  • Zure funtzioak huts egiten duenean, bidali hutsegitea emaitza-testu gisa. Modeloak orduan jakinaraz dezake edo beste dei bat eska dezake.

Eskema-gako-hitzak

parameters (input_schema /v1/messages endpoint-ean) JSON Schema bat da. Shannon 3 familiak (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) eta pisu irekiko modelo ostatatuek bidaltzen duzun bezala jasotzen dute.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro eta shannon-coder-1 modeloek azpimultzo hau jasotzen dute, hiru endpoint-etan:

Tratamendua Gako-hitzak
Bidalitako bezala irakurria Beheko errenkadetan izendatzen ez den gako-hitz oro, adibidez type, properties, required, items, enum, description, minimum, maximum, anyOf eta allOf, eskemaren maila guztietan.
format int32, int64, float, double, byte, date, date-time eta enum balioetarako irakurtzen da.
oneOf anyOf gisa irakurtzen da.
Ez da modelo hauek jasotzen duten eskemaren parte $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 eta exclusiveMaximum zenbakiak direnean; format-en beste balioak.

Portaera eta mugak

  • API-ak ez du tresna-kopuru maximorik ezartzen, ez itzuli-kopuru maximorik.
  • Eskaera-gorputzak 32 MiB arte izan dezake, eta elkarrizketak bere emaitzekin modeloaren testuinguru-leihoan sartu behar du.
  • Eskaera batek tools darabilenean, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite eta shannon-2-pro modeloek 0.2 lehenetsiko temperature erabiltzen dute. Bidali temperature beste balio bat ezartzeko.
  • Itzuli bakoitza eskaera propio bat da: zure saldotik hartzen du eta flood protection-eko kontaketan sartzen da beste edozein eskaera bezala. Mugak eta saldoa

Erroreak

Tresna-dei bat 200 egoerako ohiko erantzun bat da. Errore hauek eskaerari berari buruzkoak dira:

Egoera Mota Mezua Noiz
400 invalid_request_error unknown model: <id> model ez da argitaratutako zerrendako id bat.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools ez da array bat, edo beste eremu batek JSON mota okerra du.
413 invalid_request_error Failed to buffer the request body: … Eskaera-gorputza 32 MiB baino handiagoa da. Erroreak code: "request_too_large" darama.

Modeloak idazten ditu argumentuak. Egiaztatu zure eskemaren aurka funtzioa exekutatu aurretik, kanpoko edozein sarrera egiaztatuko zenukeen bezala.

Autentifikazio-, saldo- eta zerbitzari-erroreak eskaera guztietan bezalakoak dira. Errore‑kudeaketa