بازدان بۆ ناوەڕۆک
Bangkirina fonksiyonê

Bangkirina fonksiyonê

function ـەکانت لە داواکارییەکەدا وەسف بکە و مۆدێلەکە بە ئەو بانگکردنانە وەڵام دەداتەوە کە دەیەوێت ئەنجام بدرێن. کۆدەکەی تۆ جێبەجێیان دەکات و ئەنجامەکان دەگەڕێنێتەوە: API بانگکردنی ئامراز دەگەڕێنێتەوە و خۆی ئامراز جێبەجێ ناکات.

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

نموونەکانی ئەم لاپەڕەیە /v1/chat/completions بەکاردەهێنن. هەمان خول لەسەر /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)

یەکەم وەڵام پرسیارەکە وەڵام نادات. داوای بانگکردنێک دەکات:

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 ە.

خولەکە، هەنگاو بە هەنگاو

هەنگاو کێ چی ڕوودەدات
1 تۆ messages لەگەڵ tools بنێرە، کە لیستی ئەو function ـانەیە مۆدێلەکە دەتوانێت داوایان بکات.
2 مۆدێل وەڵامەکە tool_calls و finish_reason: "tool_calls" هەڵدەگرێت. هەر بانگکردنێک ناوی function ێک دەبات و argumentsـەکانی دەدات.
3 تۆ arguments ی هەر بانگکردنێک parse بکە و function ـەکەت جێبەجێ بکە.
4 تۆ نامەی assistant و یەک نامەی tool بۆ هەر بانگکردنێک بخەرە سەر messages، پاشان داواکارییەکە دووبارە بنێرە بە هەمان tools.
5 مۆدێل مۆدێلەکە بە دەق وەڵام دەداتەوە لەگەڵ finish_reason: "stop"، یان بانگکردنی زیاتر داوا دەکات. لەو حاڵەتەدا بگەڕێرەوە بۆ هەنگاوی 3.

یەک داواکاری یەک نۆرەی مۆدێلە. API هیچ گفتوگۆیەک لە نێوان داواکارییەکان ناهێڵێتەوە و ژمارەی خول دانانێت: کۆدەکەی تۆ messages ڕادەگرێت و بڕیار دەدات کەی بوەستێت.

پێناسەکردنی ئامرازەکان

tools ئارەیەکە بە یەک تۆمار بۆ هەر function ێک. هەموو مۆدێلێکی کاتالۆگەکە وەریدەگرێت؛ GET /v1/models بۆ هەموو id ێک capabilities.tools: true ڕاپۆرت دەکات.

بوار جۆر وەسف
type string هەمیشە function.
function.name string ئەو ناوەی مۆدێلەکە بەکاری دەهێنێت کاتێک داوای ئەم function ـە دەکات. پێویستە.
function.description string ئەوەی function ـەکە دەیکات، بە زمانی سادە.
function.parameters object Argumentsـەکان وەک JSON Schema بە type: "object" لە سەرەوە. وشە کلیلییەکانی schema لە خوارەوە ببینە.

هەر endpoint ێک شێوازی نووسینی تایبەتی خۆی هەیە بۆ ئامراز. ئەوە بنێرە کە بۆ ئەو 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 دەڵێت مۆدێلەکە دەتوانێت، یان دەبێت، ئامرازێک بانگ بکات. تەنها لەگەڵ tools پێکەوە دەخوێنرێتەوە.

بەها وەسف جێبەجێکراو لەلایەن
"auto" مۆدێلەکە بڕیار دەدات بە دەق وەڵام بداتەوە یان ئامرازێک بانگ بکات. ئەمە بنەڕەتییە. هەموو مۆدێلەکان
"required" وەڵامەکە لانیکەم یەک ئامراز بانگ دەکات. مۆدێلە open-weight ـە میوانداریکراوەکان
{"type": "function", "function": {"name": "get_weather"}} وەڵامەکە ئەم function ـە بانگ دەکات. ناوەکە دەبێت یەکێک بێت لە function ـەکانی tools. بانگکردنی function ـەکانی دیکە لە وەڵامەکە دەردەهێنرێن. مۆدێلە open-weight ـە میوانداریکراوەکان

مۆدێلەکانی Shannon (shannon-*) لە هەر داواکارییەکدا بڕیار دەدەن، وەک auto.

لەگەڵ required یان function ێکی ناونراو، finish_reason بخوێنەرەوە پێش ئەوەی tool_calls بخوێنیتەوە. کاتێک مۆدێلەکە هیچ بانگکردنێک دروست ناکات، وەڵامەکە وەڵامێکی دەقە لەگەڵ finish_reason: "stop".

واتا /v1/chat/completions /v1/responses /v1/messages
مۆدێلەکە بڕیار دەدات "auto" "auto" {"type": "auto"}
لانیکەم یەک ئامراز بانگ بکە "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. بۆ نۆرەیەک بێ بانگکردنی ئامراز، داواکارییەکە بەبێ tools بنێرە.

بانگکردنی ئامراز لە وەڵامدا

بوار جۆر وەسف
finish_reason string tool_calls کاتێک وەڵامەکە لانیکەم یەک بانگکردنی تێدایە.
message.tool_calls array یەک تۆمار بۆ هەر بانگکردنێک. بوارەکە تەنها کاتێک هەیە کە مۆدێلەکە بانگکردنێکی داوا کرد.
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 Argumentsـەکان وەک string ی JSON، "{}" کاتێک هیچ نەبێت. پێش بەکارهێنان parse ی بکە.
message.content string | null null کاتێک وەڵامەکە تەنها بانگکردنی تێدایە. مۆدێلە open-weight ـە میوانداریکراوەکان دەتوانن دەق لەتەنیشت بانگکردنەکان بگەڕێننەوە؛ مۆدێلەکانی Shannon null دەگەڕێننەوە.

هەمان بانگکردن لە هەر فۆرماتێکدا. لەسەر /v1/responses ئایتمێکی function_call ی output ە، بە arguments وەک string ی JSON. لەسەر /v1/messages بلۆکێکی ناوەڕۆکی tool_use ە کە 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\"}"
        }
      }
    ]
  }
}

چەند بانگکردنێک لە یەک نۆرەدا

وەڵامێک دەتوانێت چەند بانگکردنێک هەڵبگرێت. هەموویان جێبەجێ بکە و بۆ هەر بانگکردنێک یەک ئەنجام بنێرە، هەریەکە بە tool_call_id ی خۆی، لە داواکاری دواتردا.

مۆدێلە open-weight ـە میوانداریکراوەکان هەر بانگکردنێکی جیاواز یەک جار دەگەڕێننەوە: دوو بانگکردن بە هەمان ناو و هەمان arguments وەک یەک دەگەن.

بانگکردنی ئامرازی stream کراو

لەگەڵ stream: true، بانگکردنێک بە یەک پارچە دەگات: chunk ەکە string ی arguments ی تەواو هەڵدەگرێت، بۆیە هیچ پارچەیەک نییە بۆ بەستنەوە. index بانگکردنەکانی نۆرەکە لە 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 یەک chat.completion.chunk بۆ هەر بانگکردنێک، بە بانگکردنەکە لە delta.tool_calls[0] دا. دوایین chunk finish_reason: "tool_calls" و usage ی هەیە.
/v1/responses بۆ هەر بانگکردنێک: response.output_item.added (ئایتمێکی function_call بە arguments ی بەتاڵ)، response.function_call_arguments.delta (هەموو string ەکە)، response.function_call_arguments.done، response.output_item.done.
/v1/messages بۆ هەر بانگکردنێک: content_block_start (بلۆکی tool_use بە input ی بەتاڵ)، یەک content_block_delta کە input_json_delta.partial_json ـەکەی هەموو دەقی argumentsـەکانە، 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 هەڵدەگرێت دەقی وەڵامەکەی لە یەک delta ی content دا لە کۆتایی نۆرەکەدا دەگەیەنێت. Streaming

ناردنەوەی ئەنجامەکان

داواکاری دووەم گفتوگۆکە دووبارە دەکاتەوە و دوو شت زیاد دەکات: نۆرەی assistant کە بانگکردنەکانی داوا کرد، و یەک ئەنجام بۆ هەر بانگکردنێک.

{
  "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 وەک وەرتگرتووە بیگەڕێنەرەوە، پێش ئەنجامەکان. هەر ئەنجامێک بە id ەوە لەگەڵ بانگکردنەکەی جووت دەکرێت: tool_call_id لەسەر /v1/chat/completions، call_id لەسەر /v1/responses، tool_use_id لەسەر /v1/messages.
  • ئەنجام دەقە. ئۆبجێکت بکە بە string ی JSON بۆ content (output لەسەر /v1/responses). لەسەر /v1/messages content ی بلۆکی tool_result string ێکە یان لیستێکی بلۆکی دەق.
  • لە نۆرەی assistant دا، function.arguments هەر string ی JSON دەمێنێتەوە، وەک خۆی هاتووە.
  • گفتوگۆکە دەکرێت بە ئەنجامی ئامرازێک کۆتایی بێت. پێویستی بە نامەی نوێی بەکارهێنەر نییە: مۆدێلەکە لە ئەنجامەکەوە بەردەوام دەبێت.
  • کاتێک function ـەکەت شکست دەخوات، شکستەکە وەک دەقی ئەنجام بنێرە. مۆدێلەکە دەتوانێت ڕاپۆرتی بکات یان بانگکردنێکی دیکە داوا بکات.

وشە کلیلییەکانی schema

parameters (input_schema لەسەر /v1/messages) 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 ئەم بەشە وەردەگرن، لەسەر هەر سێ endpoint ـەکە:

مامەڵەکردن وشە کلیلییەکان
وەک نێردراو دەخوێنرێتەوە هەموو وشە کلیلییەک کە لە ڕیزەکانی خوارەوەدا ناو نەبرابێت، بۆ نموونە 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 هیچ زۆرینەی ژمارەی ئامراز و هیچ زۆرینەی ژمارەی خول دانانێت.
  • body ی داواکاری دەتوانێت تا 32 MiB بێت، و گفتوگۆکە لەگەڵ ئەنجامەکانی دەبێت لە context window ی مۆدێلەکە بگونجێت.
  • کاتێک داواکارییەک tools هەڵدەگرێت، shannon-1.6-lite، shannon-1.6-pro، shannon-2-lite و shannon-2-pro temperature ی بنەڕەتی 0.2 بەکاردەهێنن. temperature بنێرە بۆ دانانی بەهایەکی دیکە.
  • هەر خولێک داواکارییەکی جیاوازە: لە باڵانسەکەت دەخوات و وەک هەر داواکارییەکی دیکە لە flood protection دا هەژمار دەکرێت. سنوور و باڵانس

هەڵەکان

بانگکردنی ئامراز وەڵامێکی ئاساییە بە status ی 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: … body ی داواکارییەکە لە 32 MiB گەورەترە. هەڵەکە code: "request_too_large" هەڵدەگرێت.

مۆدێلەکە argumentsـەکان دەنووسێت. پێش جێبەجێکردنی function ـەکە بەراورد بیان بکە لەگەڵ schema ـکەت، وەک هەر input ێکی دەرەکی.

هەڵەکانی authentication، باڵانس و سێرڤەر هەمان هی هەموو داواکارییەکن. Çewtî