فنکشن زنګ وهل
خپل 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) 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"]
}
}
}]
}' لومړی ځواب پوښتنې ته ځواب نه ورکوي. دا call غواړي:
{
"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"]
}
}
} {
"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 وايي چې ماډل ته اجازه ده، یا باید، 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\"}"
}
}
]
}
} {
"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"}
}
]
} په یوه turn کې څو calls
ځواب کولی شي څو calls ولري. هر یو چلوئ او په راتلونکې غوښتنه کې د هر call لپاره یوه پایله ولیږئ، هره د خپل tool_call_id سره.
کوربه شوي open-weight ماډلونه هر جلا call یو ځل بیرته ورکوي: دوه calls چې همغه نوم او همغه آرګومنټونه ولري د یوه په توګه رارسیږي.
Stream شوي tool calls
د stream: true سره، call په یوه ټوټه رارسیږي: chunk بشپړ arguments string لري، نو د یوځای کولو لپاره هیڅ ټوټې نشته. index د turn calls له 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 | د هر 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\"}"
}
]
} {
"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 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_resultblockcontentstring یا د متن 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 تېروتنې د هرې غوښتنې په څیر دي. د تېروتنې اداره کول