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) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const 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"],
},
},
}];
// Your code: ask a weather service here.
function getWeather({ city, unit = "celsius" }) {
return { city, temperature: 18, unit, conditions: "cloudy" };
}
const messages = [{ role: "user", content: "What is the weather in Paris right now?" }];
let answer = null;
// The API sets no limit on rounds: set your own.
for (let round = 0; round < 5; round++) {
const response = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
messages,
tools,
});
const choice = response.choices[0];
if (choice.finish_reason !== "tool_calls") {
answer = choice.message.content;
break;
}
messages.push(choice.message); // the assistant turn with its tool_calls
for (const call of choice.message.tool_calls) {
const args = JSON.parse(call.function.arguments); // arguments is a JSON string
messages.push({
role: "tool",
tool_call_id: call.id,
content: JSON.stringify(getWeather(args)),
});
}
}
console.log(answer); # 1. Send the conversation with the tools.
curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"}
],
"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"]
}
}
}]
}'
# 2. Run the function yourself, then send the assistant turn and the result.
# Use the id of the call you received.
curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"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\"}"}
],
"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"]
}
}
}]
}' یەکەم وەڵام پرسیارەکە وەڵام نادات. داوای بانگکردنێک دەکات:
{
"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"]
}
}
} {
"type": "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"]
}
} {
"name": "get_weather",
"description": "Get the current weather for a city.",
"input_schema": {
"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\"}"
}
}
]
}
} {
"output": [
{
"id": "fc_3d2c1b0a9f8e4d7c6b5a4f3e2d1c0b9a",
"type": "function_call",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}",
"status": "completed"
}
]
} {
"stop_reason": "tool_use",
"content": [
{
"type": "tool_use",
"id": "toolu_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"input": {"city": "Paris"}
}
]
} چەند بانگکردنێک لە یەک نۆرەدا
وەڵامێک دەتوانێت چەند بانگکردنێک هەڵبگرێت. هەموویان جێبەجێ بکە و بۆ هەر بانگکردنێک یەک ئەنجام بنێرە، هەریەکە بە tool_call_id ی خۆی، لە داواکاری دواتردا.
مۆدێلە open-weight ـە میوانداریکراوەکان هەر بانگکردنێکی جیاواز یەک جار دەگەڕێننەوە: دوو بانگکردن بە هەمان ناو و هەمان arguments وەک یەک دەگەن.
بانگکردنی ئامرازی stream کراو
لەگەڵ stream: true، بانگکردنێک بە یەک پارچە دەگات: chunk ەکە string ی arguments ی تەواو هەڵدەگرێت، بۆیە هیچ پارچەیەک نییە بۆ بەستنەوە. index بانگکردنەکانی نۆرەکە لە 0 ەوە هەژمار دەکات.
{
"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\"}"
}
]
} {
"input": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{
"type": "function_call",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
},
{
"type": "function_call_output",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"output": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"
}
]
} {
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"input": {"city": "Paris"}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_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/messagescontentی بلۆکیtool_resultstring ێکە یان لیستێکی بلۆکی دەق. - لە نۆرەی 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-protemperatureی بنەڕەتی 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î