Wacyigelinta Shaqada
Ku sharax functions-kaaga codsiga model-kuna wuxuu ku jawaabayaa wicitaannada uu rabo in la sameeyo. Code-kaagu wuu orodsiiyaa oo natiijooyinka dib buu u diraa: API-gu wuxuu soo celiyaa wicitaannada tool laftiisa tool ma orodsiiyo.
POST https://api.shannon-ai.com/v1/chat/completions
Tusaalayaasha bogga waxay isticmaalaan /v1/chat/completions. Isla wareegga ayaa ka shaqeeya /v1/responses iyo /v1/messages; halka qaab uu wax si kale u qoro, qaybaha hoose waxay muujinayaan saddexdaba.
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"]
}
}
}]
}' Jawaabta ugu horreysa su'aasha ma jawaabto. Waxay codsataa wicitaan:
{
"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}
}
} Ka dib marka aad natiijada dirto, jawaabta xigta waa jawaab caadi ah: message.content wuxuu haystaa qoraalka finish_reason-na waa stop.
Wareegga, tallaabo-tallaabo
| Tallaabo | Yaa | Waxa dhaca |
|---|---|---|
| 1 | Adiga | Dir messages iyo tools, liiska functions-ka model-ku codsan karo. |
| 2 | Model | Jawaabtu waxay sidaa tool_calls iyo finish_reason: "tool_calls". Wicitaan kastaa wuxuu magacaabaa function wuxuuna bixiyaa arguments-kiisa. |
| 3 | Adiga | Parse-garee arguments wicitaan kasta oo orodsii function-kaaga. |
| 4 | Adiga | Ku dar fariinta assistant-ka iyo hal fariin tool wicitaan kasta messages, kaddib mar kale dir codsiga isla tools. |
| 5 | Model | Model-ku wuxuu ku jawaabaa qoraal oo leh finish_reason: "stop", ama wuxuu codsadaa wicitaanno dheeraad ah. Xaaladdaas dib ugu noqo tallaabada 3. |
Hal codsi waa hal wareeg model. API-gu wada-hadal u dhexeeya codsiyada ma hayo, tiro wareegyo ahna ma dejiyo: code-kaagu wuxuu hayaa messages wuxuuna go'aamiyaa goorta la joojinayo.
Qeexidda tools
tools waa array leh hal gelin function kasta. Model kasta oo kataloogga ahi wuu aqbalaa; GET /v1/models wuxuu id kasta u sheegaa capabilities.tools: true.
| Field | Nooc | Sharaxaad |
|---|---|---|
type | string | Had iyo jeer function. |
function.name | string | Magaca model-ku isticmaalo marka uu function-kan codsado. Loo baahan yahay. |
function.description | string | Waxa function-ku sameeyo, luqad cad. |
function.parameters | object | Arguments-ka sida JSON Schema oo type: "object" ugu sarreeyo. Eeg Erayada schema hoose. |
Endpoint kastaa wuxuu leeyahay qoraal u gaar ah oo tool ah. Dir kan endpoint-ka aad wacayso ka tirsan:
{
"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 wuxuu sheegaa in model-ku wici karo, ama waajib tahay inuu wacdo, tool. Waxaa la akhriyaa tools la socda oo keliya.
| Qiime | Sharaxaad | Waxay dabaqaan |
|---|---|---|
"auto" | Model-ku wuxuu go'aansadaa inuu ku jawaabo qoraal ama inuu wacdo tool. Kani waa default-ka. | Dhammaan model-yada |
"required" | Jawaabtu waxay wacdaa ugu yaraan hal tool. | Model-yada open-weight ee la martigeliyo |
{"type": "function", "function": {"name": "get_weather"}} | Jawaabtu waxay wacdaa function-kan. Magacu waa inuu ahaadaa mid ka mid ah functions-ka tools. Wicitaannada functions-ka kale jawaabta laga tagaa. | Model-yada open-weight ee la martigeliyo |
Model-yada Shannon (shannon-*) codsi kasta ayay go'aansadaan, sida auto.
Marka required ama function la magacaabay, akhri finish_reason ka hor inta aadan akhrin tool_calls. Marka model-ku wicitaan soo saarin, jawaabtu waa jawaab qoraal ah oo leh finish_reason: "stop".
| Macne | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Model-ku wuu go'aansadaa | "auto" | "auto" | {"type": "auto"} |
| Wac ugu yaraan hal tool | "required" | "required" | {"type": "any"} |
| Wac hal function oo la magacaabay | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
La aqbalay u waafaqsanaan: tool_choice: "none" iyo parallel_tool_calls. Wareeg aan lahayn wicitaannada tool, codsiga dir tools la'aantiis.
Wicitaannada tool jawaabta ku jira
| Field | Nooc | Sharaxaad |
|---|---|---|
finish_reason | string | tool_calls marka jawaabtu sidato ugu yaraan hal wicitaan. |
message.tool_calls | array | Hal gelin wicitaan kasta. Field-ku wuxuu jiraa marka model-ku wicitaan codsaday oo keliya. |
tool_calls[].id | string | call_ oo ay raacayso 32 xaraf hexadecimal ah. Dib ugu dir sida tool_call_id natiijada la socota. |
tool_calls[].type | string | Had iyo jeer function. |
tool_calls[].function.name | string | Function-ka la orodsiinayo. |
tool_calls[].function.arguments | string | Arguments-ka sida string JSON ah, "{}" marka midna jirin. Parse-garee ka hor isticmaalka. |
message.content | string | null | null marka jawaabtu wicitaanno keliya haysato. Model-yada open-weight ee la martigeliyo way soo celin karaan qoraal wicitaannada agtooda; model-yada Shannon waxay soo celiyaan null. |
Isla wicitaanka qaab kasta. /v1/responses waa shay function_call ah oo ka mid ah output, oo leh arguments sida string JSON ah. /v1/messages waa content block tool_use oo input kiisu yahay shay JSON ah, id kiisu ku bilaabmo toolu_, stop_reason-na yahay 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"}
}
]
} Dhowr wicitaan hal wareeg
Jawaab waxay sidi kartaa dhowr wicitaan. Dhammaantood orodsii oo hal natiijo wicitaan kasta dir, mid kastaa wuxuu leeyahay tool_call_id u gaar ah, codsiga xiga.
Model-yada open-weight ee la martigeliyo wicitaan kasta oo kala duwan hal mar ayay soo celiyaan: laba wicitaan oo isla magac iyo isla arguments leh waxay u yimaadaan sida mid.
Wicitaannada tool ee stream-ka
Marka stream: true, wicitaan wuxuu u yimaadaa hal gabal: chunk-gu wuxuu haystaa string-ka arguments oo dhammaystiran, sidaas darteed qaybo la isku xiro ma jiraan. index wuxuu tiriyaa wicitaannada wareegga laga bilaabo 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 | Waxa yimaada |
|---|---|
/v1/chat/completions | Hal chat.completion.chunk wicitaan kasta, wicitaanka oo ku jira delta.tool_calls[0]. Chunk-ga ugu dambeeya wuxuu leeyahay finish_reason: "tool_calls" iyo usage. |
/v1/responses | Wicitaan kasta: response.output_item.added (shay function_call oo leh arguments madhan), response.function_call_arguments.delta (string-ka oo dhan), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Wicitaan kasta: content_block_start (block tool_use oo leh input madhan), hal content_block_delta oo input_json_delta.partial_json yahay qoraalka arguments-ka oo dhan, content_block_stop. message_delta kaddib wuxuu sidaa stop_reason: "tool_use". |
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro iyo shannon-coder-1, codsi stream ah oo sida tools wuxuu qoraalka jawaabtiisa ku gaarsiiyaa hal delta content dhammaadka wareegga. Streaming
Dib u dirista natiijooyinka
Codsiga labaad wuxuu ku celiyaa wada-hadalka wuxuuna ku daraa laba shay: wareegga assistant-ka ee wicitaannada codsaday, iyo hal natiijo wicitaan kasta.
{
"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\"}"
}
]
}
]
} - Wareegga assistant-ka dib ugu dir sida aad u heshay, ka hor natiijooyinka. Natiij kasta waxaa wicitaankeeda lagu waafajiyaa id:
tool_call_id/v1/chat/completions,call_id/v1/responses,tool_use_id/v1/messages. - Natiijadu waa qoraal. U serialize-garee shay string JSON ah
content(output/v1/responses)./v1/messagescontentee block-gatool_resultwaa string ama liis blocks qoraal ah. - Wareegga assistant-ka,
function.argumentswuxuu ahaanayaa string JSON ah, sida uu u yimid. - Wada-hadalku wuxuu ku dhammaan karaa natiijo tool. Fariin isticmaale oo cusub looma baahna: model-ku wuxuu ka sii wadaa natiijada.
- Marka function-kaagu fashilmo, fashilka u dir sida qoraalka natiijada. Model-ku kaddib wuu sheegi karaa ama wuxuu codsan karaa wicitaan kale.
Erayada schema
parameters (input_schema /v1/messages) waa JSON Schema. Qoyska Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) iyo model-yada open-weight ee la martigeliyo way helaan sida aad u dirto.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro iyo shannon-coder-1 waxay helaan qayb-yar kan, saddexda endpoint:
| Maareyn | Erayo muhiim ah |
|---|---|
| Waxaa la akhriyaa sida loo diray | Eray kasta oo aan lagu magacaabin safafka hoose, tusaale ahaan type, properties, required, items, enum, description, minimum, maximum, anyOf iyo allOf, heer kasta oo schema-ha ah. |
format | Waxaa la akhriyaa qiimayaasha int32, int64, float, double, byte, date, date-time iyo enum. |
oneOf | Waxaa loo akhriyaa sida anyOf. |
| Qayb ma aha schema-ha model-yadani helaan | $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 iyo exclusiveMaximum marka ay yihiin tirooyin; qiimayaasha kale ee format. |
Dabeecad iyo xadad
- API-gu ma dejiyo tirada ugu badan ee tools ama tirada ugu badan ee wareegyada.
- Jidhka codsigu wuxuu noqon karaa ilaa 32 MiB, wada-hadalka iyo natiijooyinkiisuna waa inay ku soo galaan context window-ka model-ka.
- Marka codsi sido
tools,shannon-1.6-lite,shannon-1.6-pro,shannon-2-liteiyoshannon-2-prowaxay isticmaalaantemperaturedefault ah oo ah 0.2. Dirtemperaturesi aad u dejiso qiime kale. - Wareeg kastaa waa codsi u gaar ah: wuxuu ka qaadaa haraaggaaga wuxuuna ka tirsan yahay flood protection sida codsi kasta oo kale. Xadad iyo haraag
Khaladaad
Wicitaanka tool waa jawaab caadi ah oo leh xaalad 200. Khaladaadkan waxay khusaan codsiga laftiisa:
| Xaalad | Nooc | Fariin | Goorta |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model ma aha id ka mid ah liiska la daabacay. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools ma aha array, ama field kale wuxuu leeyahay nooc JSON qaldan. |
413 | invalid_request_error | Failed to buffer the request body: … | Jidhka codsigu wuu ka weyn yahay 32 MiB. Khaladku wuxuu sidaa code: "request_too_large". |
Model-ku wuxuu qoraa arguments-ka. Ku hubi schema-gaaga ka hor inta aadan orodsiin function-ka, sida aad u hubin lahayd input kasta oo dibadda ka yimaada.
Xaqiijinta, haraagga iyo khaladaadka server-ku waa isku mid codsi kasta. Khaladaadka Maareynta