منځپانګې ته ټوپ ووهئ
فنکشن زنګ وهل

فنکشن زنګ وهل

خپل functions په غوښتنه کې بیان کړئ او ماډل هغو calls سره ځواب ورکوي چې غواړي وشي. ستاسو کوډ یې چلوي او پایلې بیرته لیږي: API tool calls بیرته ورکوي او پخپله tool نه چلوي.

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

پدې پاڼه کې نمونې /v1/chat/completions کاروي. هماغه loop په /v1/responses او /v1/messages هم چلیږي؛ هلته چې بڼه یو شی بل ډول لیکي، لاندې برخې ټول درې ښيي.

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)

لومړی ځواب پوښتنې ته ځواب نه ورکوي. دا call غواړي:

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

وروسته له دې چې پایله ولیږئ، راتلونکی ځواب عادي ځواب دی: message.content متن لري او finish_reason stop دی.

Loop، ګام په ګام

ګام څوک څه کیږي
1 تاسو messages د tools سره یوځای ولیږئ، د functions لیست چې ماډل یې غوښتلی شي.
2 ماډل ځواب tool_calls او finish_reason: "tool_calls" لري. هر call یو function نوموي او خپل آرګومنټونه ورکوي.
3 تاسو د هر call arguments parse کړئ او خپل function وچلوئ.
4 تاسو د assistant message او د هر call لپاره یو tool message messages ته اضافه کړئ، بیا غوښتنه د هماغه tools سره بیا ولیږئ.
5 ماډل ماډل په متن سره د finish_reason: "stop" ځواب ورکوي، یا نور calls غواړي. پدې حالت کې ګام 3 ته ستانه شئ.

یوه غوښتنه د ماډل یو turn دی. API د غوښتنو ترمنځ ګفتګه نه ساتي او د پړاوونو شمیر نه ټاکي: ستاسو کوډ messages ساتي او پریکړه کوي چې کله ودریږي.

د Tools تعریفول

tools یوه لړۍ ده چې د هر function لپاره یوه داخله لري. د کتلاګ هر ماډل یې مني؛ GET /v1/models د هر id لپاره capabilities.tools: true راپور کوي.

ساحه ډول تشریح
type string تل function.
function.name string هغه نوم چې ماډل یې کاروي کله چې دا function غواړي. اړین.
function.description string function څه کوي، په ساده ژبه.
function.parameters object آرګومنټونه د JSON Schema په توګه چې په سر کې type: "object" لري. لاندې د Schema کلیدي کلمې وګورئ.

هر endpoint د tool خپل لیکلو ډول لري. هغه یې ولیږئ چې د هغه endpoint سره تړاو لري چې غوښتنه یې کوئ:

{
  "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 وايي چې ماډل ته اجازه ده، یا باید، tool وغواړي. دا یوازې د tools سره یوځای لوستل کیږي.

ارزښت تشریح پلي کوونکی
"auto" ماډل پریکړه کوي چې په متن ځواب ورکړي که tool وغواړي. دا ډیفالټ دی. ټول ماډلونه
"required" ځواب لږ تر لږه یو tool غواړي. کوربه شوي open-weight ماډلونه
{"type": "function", "function": {"name": "get_weather"}} ځواب دا function غواړي. نوم باید په tools کې له functions څخه یو وي. نورو functions ته calls له ځواب څخه وتل کیږي. کوربه شوي open-weight ماډلونه

د Shannon ماډلونه (shannon-*) په هره غوښتنه کې پریکړه کوي، لکه د auto سره.

د required یا نومول شوې function سره، مخکې له tool_calls لوستلو finish_reason ولولئ. کله چې ماډل هیڅ call نه جوړوي، ځواب د متن ځواب دی چې finish_reason: "stop" لري.

معنی /v1/chat/completions /v1/responses /v1/messages
ماډل پریکړه کوي "auto" "auto" {"type": "auto"}
لږ تر لږه یو tool وغواړه "required" "required" {"type": "any"}
یو نومول شوی function وغواړه {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

د مطابقت لپاره منل شوي: tool_choice: "none" او parallel_tool_calls. د هغه turn لپاره چې tool calls نه لري، غوښتنه پرته له tools ولیږئ.

په ځواب کې Tool calls

ساحه ډول تشریح
finish_reason string tool_calls کله چې ځواب لږ تر لږه یو call ولري.
message.tool_calls array د هر call لپاره یوه داخله. ساحه یوازې هغه وخت شتون لري کله چې ماډل call غوښتی وي.
tool_calls[].id string call_ چې ورپسې 32 هیکساډیسیمل توري راځي. دا د پایلې سره د tool_call_id په توګه بیرته ولیږئ.
tool_calls[].type string تل function.
tool_calls[].function.name string هغه function چې باید چلول شي.
tool_calls[].function.arguments string آرګومنټونه د JSON string په توګه، "{}" کله چې هیڅ نه وي. مخکې له کارولو یې parse کړئ.
message.content string | null null کله چې ځواب یوازې calls لري. کوربه شوي open-weight ماډلونه کولی شي د calls تر څنګ متن بیرته ورکړي؛ د Shannon ماډلونه null بیرته ورکوي.

همدا call په هره بڼه کې. په /v1/responses کې دا د output یو function_call توکی دی، چې arguments یې د JSON string په توګه دي. په /v1/messages کې دا tool_use منځپانګې block دی چې input یې د JSON څیز دی، id یې په toolu_ پیلیږي، او stop_reason یې 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\"}"
        }
      }
    ]
  }
}

په یوه turn کې څو calls

ځواب کولی شي څو calls ولري. هر یو چلوئ او په راتلونکې غوښتنه کې د هر call لپاره یوه پایله ولیږئ، هره د خپل tool_call_id سره.

کوربه شوي open-weight ماډلونه هر جلا call یو ځل بیرته ورکوي: دوه calls چې همغه نوم او همغه آرګومنټونه ولري د یوه په توګه رارسیږي.

Stream شوي tool calls

د stream: true سره، call په یوه ټوټه رارسیږي: chunk بشپړ arguments string لري، نو د یوځای کولو لپاره هیڅ ټوټې نشته. index د turn calls له 0 څخه شمیري.

data: یو chunk، بڼه شوی
{
  "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 څه رارسیږي
/v1/chat/completions د هر call لپاره یو chat.completion.chunk، د call سره په delta.tool_calls[0] کې. وروستی chunk finish_reason: "tool_calls" او usage لري.
/v1/responses د هر call لپاره: response.output_item.added (د خالي arguments سره function_call توکی)، response.function_call_arguments.delta (ټول string)، response.function_call_arguments.done، response.output_item.done.
/v1/messages د هر call لپاره: content_block_start (د خالي input سره tool_use block)، یو content_block_delta چې input_json_delta.partial_json یې ټول آرګومنټونو متن دی، content_block_stop. بیا message_delta د stop_reason: "tool_use" سره راځي.

په shannon-1.6-lite، shannon-1.6-pro، shannon-2-lite، shannon-2-pro او shannon-coder-1 کې، stream شوې غوښتنه چې tools لري خپل د ځواب متن د turn په پای کې په یوه content delta کې وړاندې کوي. جریان

د پایلو بیرته لیږل

دویمه غوښتنه ګفتګه تکراروي او دوه شیان زیاتوي: د assistant turn چې calls یې غوښتل، او د هر call لپاره یوه پایله.

{
  "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\"}"
    }
  ]
}
  • د assistant turn هماغسې بیرته ولیږئ لکه څنګه چې مو ترلاسه کړ، مخکې له پایلو. هره پایله د id په واسطه له خپل call سره سمون خوري: په /v1/chat/completions کې tool_call_id، په /v1/responses کې call_id، په /v1/messages کې tool_use_id.
  • پایله متن ده. څیز د JSON string ته سیریلایز کړئ د content لپاره (په /v1/responses کې output). په /v1/messages کې د tool_result block content string یا د متن blocks لیست دی.
  • د assistant په turn کې، function.arguments د JSON string په توګه پاتې کیږي، لکه څنګه چې رسیدلی.
  • ګفتګه کولی شي د tool پایلې سره پای ته ورسیږي. نوي user message ته اړتیا نشته: ماډل له پایلې دوام کوي.
  • کله چې ستاسو function ناکام شي، ناکامي د پایلې متن په توګه ولیږئ. ماډل بیا کولی شي دا راپور کړي یا بل call وغواړي.

د Schema کلیدي کلمې

parameters (په /v1/messages کې input_schema) JSON Schema دی. د Shannon 3 کورنۍ (shannon-3، shannon-3-pro، shannon-3.1، shannon-3.1-pro) او کوربه شوي open-weight ماډلونه یې هماغسې ترلاسه کوي لکه تاسو چې لیږئ.

shannon-1.6-lite، shannon-1.6-pro، shannon-2-lite، shannon-2-pro او shannon-coder-1 دا فرعي سیټ په ټولو درېیو endpoints کې ترلاسه کوي:

چلند کلیدي کلمې
لکه لیږل شوي لوستل کیږي هره کلیدي کلمه چې په لاندې قطارونو کې نه ده نومول شوې، د مثال په توګه type، properties، required، items، enum، description، minimum، maximum، anyOf او allOf، د schema په هره کچه کې.
format د ارزښتونو int32، int64، float، double، byte، date، date-time او enum لپاره لوستل کیږي.
oneOf د anyOf په توګه لوستل کیږي.
د هغه schema برخه نه دي چې دا ماډلونه ترلاسه کوي $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 او exclusiveMaximum کله چې شمیرې وي؛ د format نور ارزښتونه.

چلند او حدونه

  • API د tools لپاره هیڅ اعظمي شمیر او د پړاوونو لپاره هیڅ اعظمي شمیر نه ټاکي.
  • د غوښتنې بدنه تر 32 MiB پورې کیدی شي، او ګفتګه د خپلو پایلو سره باید د ماډل په context window کې ځای شي.
  • کله چې غوښتنه tools ولري، shannon-1.6-lite، shannon-1.6-pro، shannon-2-lite او shannon-2-pro د 0.2 ډیفالټ temperature کاروي. بل ارزښت ټاکلو لپاره temperature ولیږئ.
  • هر پړاو خپله غوښتنه ده: دا ستاسو له بیلانس اخلي او د هرې بلې غوښتنې په څیر د flood protection په شمیرنه کې راځي. حدونه او بیلانس

تېروتنې

Tool call عادي ځواب دی چې حالت یې 200 دی. دا تېروتنې پخپله غوښتنې پورې اړه لري:

حالت ډول پیغام کله
400 invalid_request_error unknown model: <id> model د خپور شوي لیست id نه دی.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools لړۍ نه ده، یا بله ساحه د JSON غلط ډول لري.
413 invalid_request_error Failed to buffer the request body: … د غوښتنې بدنه له 32 MiB څخه لویه ده. تېروتنه code: "request_too_large" لري.

ماډل آرګومنټونه لیکي. مخکې له دې چې function چلوئ، یې د خپل schema پر ضد وګورئ، لکه څنګه چې هر بهرنی input کتئ.

تصدیق، بیلانس او server تېروتنې د هرې غوښتنې په څیر دي. د تېروتنې اداره کول