කාර්ය කැඳවීම
ඉල්ලීමේ ඔබේ functions විස්තර කරන්න, එවිට model එක සිදු කිරීමට අවශ්ය calls සමඟ පිළිතුරු දෙයි. ඔබේ code එක ඒවා ක්රියාත්මක කර ප්රතිඵල ආපසු යවයි: API එක tool calls ආපසු දෙන අතර tool එකක් තනිවම ක්රියාත්මක නොකරයි.
POST https://api.shannon-ai.com/v1/chat/completions
මෙම පිටුවේ නියැදි /v1/chat/completions භාවිතා කරයි. එම loop එකම /v1/responses සහ /v1/messages හි ද ධාවනය වේ; format එකක් යමක් වෙනස් ලෙස ලියන තැන්වල, පහත කොටස් තුනම පෙන්වයි.
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 සමඟ model එකට ඉල්ලිය හැකි functions ලැයිස්තුව වන tools යවන්න. |
| 2 | Model එක | පිළිතුර tool_calls සහ finish_reason: "tool_calls" රැගෙන යයි. සෑම call එකක්ම function එකක් නම් කර එහි arguments දෙයි. |
| 3 | ඔබ | සෑම call එකකම arguments parse කර ඔබේ function එක ක්රියාත්මක කරන්න. |
| 4 | ඔබ | Assistant පණිවිඩය සහ call එකකට එක tool පණිවිඩය බැගින් messages වලට එකතු කර, එම tools සමඟම ඉල්ලීම නැවත යවන්න. |
| 5 | Model එක | Model එක finish_reason: "stop" සමඟ පෙළෙන් පිළිතුරු දෙයි, නැතහොත් තවත් calls ඉල්ලයි. එම අවස්ථාවේදී 3 පියවරට ආපසු යන්න. |
එක ඉල්ලීමක් යනු එක model turn එකකි. API එක ඉල්ලීම් අතර සංවාදයක් තබා නොගන්නා අතර වට ගණනක් නියම නොකරයි: messages තබාගෙන කවදා නතර කරන්නේදැයි තීරණය කරන්නේ ඔබේ code එකයි.
Tools අර්ථ දැක්වීම
tools යනු function එකකට එක entry බැගින් ඇති array එකකි. නාමාවලියේ සෑම model එකක්ම එය පිළිගනී; GET /v1/models සෑම id එකකටම capabilities.tools: true වාර්තා කරයි.
| Field | වර්ගය | විස්තරය |
|---|---|---|
type | string | සෑම විටම function. |
function.name | string | Model එක මෙම function එක ඉල්ලන විට භාවිතා කරන නම. අවශ්යයි. |
function.description | string | Function එක කරන දේ, සරල භාෂාවෙන්. |
function.parameters | object | Arguments ඉහළින් type: "object" සහිත JSON Schema එකක් ලෙස. පහත Schema keywords බලන්න. |
සෑම endpoint එකකටම tool එකක් ලියන්නේ කෙසේද යන්න ගැන තමන්ගේම ආකාරයක් ඇත. ඔබ call කරන 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 මගින් model එකට tool එකක් call කළ හැකිද, නැතහොත් කළ යුතුද යන්න කියයි. එය කියවන්නේ tools සමඟ පමණි.
| අගය | විස්තරය | යොදන්නේ |
|---|---|---|
"auto" | පෙළෙන් පිළිතුරු දෙනවාද tool එකක් call කරනවාද යන්න model එක තීරණය කරයි. මෙය පෙරනිමියයි. | සියලු models |
"required" | පිළිතුර අවම වශයෙන් එක tool එකක් call කරයි. | අපගේ සේවාදායකවල ධාවනය වන open-weight models |
{"type": "function", "function": {"name": "get_weather"}} | පිළිතුර මෙම function එක call කරයි. නම tools හි ඇති functions වලින් එකක් විය යුතුය. වෙනත් functions වලට calls පිළිතුරෙන් ඉවත් කෙරේ. | අපගේ සේවාදායකවල ධාවනය වන open-weight models |
Shannon models (shannon-*) auto සමඟ මෙන් සෑම ඉල්ලීමකදීම තීරණය කරයි.
required හෝ නම් කළ function එකක් සමඟ, tool_calls කියවීමට පෙර finish_reason කියවන්න. Model එක call එකක් නිපදවන්නේ නැති විට, පිළිතුර finish_reason: "stop" සහිත පෙළ පිළිතුරක් වේ.
| තේරුම | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Model එක තීරණය කරයි | "auto" | "auto" | {"type": "auto"} |
| අවම වශයෙන් එක tool එකක් call කරන්න | "required" | "required" | {"type": "any"} |
| නම් කළ එක function එකක් call කරන්න | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
අනුකූලතාව සඳහා පිළිගනී: tool_choice: "none" සහ parallel_tool_calls. Tool calls නැති turn එකක් සඳහා, ඉල්ලීම tools නොමැතිව යවන්න.
පිළිතුරේ tool calls
| Field | වර්ගය | විස්තරය |
|---|---|---|
finish_reason | string | පිළිතුරේ අවම වශයෙන් එක call එකක් ඇති විට tool_calls. |
message.tool_calls | array | Call එකකට එක entry බැගින්. Model එක call එකක් ඉල්ලූ විට පමණක් field එක ඇත. |
tool_calls[].id | string | call_ ට පසුව hexadecimal අක්ෂර 32ක්. ප්රතිඵලය සමඟ එය tool_call_id ලෙස ආපසු යවන්න. |
tool_calls[].type | string | සෑම විටම function. |
tool_calls[].function.name | string | ක්රියාත්මක කළ යුතු function එක. |
tool_calls[].function.arguments | string | Arguments JSON string එකක් ලෙස, නොමැති විට "{}". භාවිතයට පෙර එය parse කරන්න. |
message.content | string | null | පිළිතුරේ calls පමණක් ඇති විට null. අපගේ සේවාදායකවල ධාවනය වන open-weight models වලට calls අසල පෙළ ආපසු දිය හැක; Shannon models null ආපසු දෙයි. |
එම call එකම සෑම format එකකම. /v1/responses හි එය output හි function_call item එකකි, arguments JSON string එකක් ලෙස. /v1/messages හි එය input JSON object එකක් වන tool_use content block එකකි, එහි 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 කිහිපයක් තිබිය හැක. ඒ සියල්ලම ක්රියාත්මක කර, ඊළඟ ඉල්ලීමේදී ඒ සෑම එකකටම තමන්ගේම tool_call_id සමඟ call එකකට එක ප්රතිඵලය බැගින් යවන්න.
අපගේ සේවාදායකවල ධාවනය වන open-weight models සෑම වෙනස් call එකක්ම එක වරක් ආපසු දෙයි: එකම නම සහ එකම arguments ඇති 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 item එකක්), 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 එකක්), input_json_delta.partial_json සම්පූර්ණ arguments පෙළ වන එක content_block_delta එකක්, 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 මත, tools රැගෙන යන stream කළ ඉල්ලීමක් එහි පිළිතුරේ පෙළ turn එකේ අවසානයේ එක content delta එකකින් ලබා දෙයි. ස්ට්රීමිං
ප්රතිඵල ආපසු යැවීම
දෙවන ඉල්ලීම සංවාදය නැවත ලියා දේවල් දෙකක් එකතු කරයි: calls ඉල්ලූ assistant turn එක, සහ 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 එක ප්රතිඵලවලට පෙර ඔබට ලැබුණු ආකාරයටම ආපසු යවන්න. සෑම ප්රතිඵලයක්ම එහි call එකට id මගින් ගැළපේ:
/v1/chat/completionsහිtool_call_id,/v1/responsesහිcall_id,/v1/messagesහිtool_use_id. - ප්රතිඵලයක් යනු පෙළකි. Object එකක්
contentසඳහා (/v1/responsesහිoutput) JSON string එකකට serialise කරන්න./v1/messagesහිtool_resultblock එකකcontentstring එකක් හෝ text blocks ලැයිස්තුවක් වේ. - Assistant turn එකේ,
function.argumentsඑය පැමිණි ආකාරයටම JSON string එකක් ලෙස පවතී. - සංවාදය tool ප්රතිඵලයකින් අවසන් විය හැක. නව user පණිවිඩයක් අවශ්ය නැත: model එක ප්රතිඵලයෙන් දිගටම කරගෙන යයි.
- ඔබේ function එක අසාර්ථක වූ විට, අසාර්ථකත්වය ප්රතිඵල පෙළ ලෙස යවන්න. එවිට model එකට එය වාර්තා කිරීමට හෝ වෙනත් 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 models එය ඔබ යවන ආකාරයටම ලබා ගනී.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro සහ shannon-coder-1 endpoints තුනේම මෙම උප කුලකය ලබා ගනී:
| සැලකීම | මූල පද (Keywords) |
|---|---|
| යැවූ ආකාරයටම කියවයි | පහත පේළිවල නම් නොකළ සෑම මූල පදයක්ම, උදාහරණයක් ලෙස type, properties, required, items, enum, description, minimum, maximum, anyOf සහ allOf, schema එකේ සෑම මට්ටමකම. |
format | int32, int64, float, double, byte, date, date-time සහ enum යන අගයන් සඳහා කියවයි. |
oneOf | anyOf ලෙස කියවයි. |
| මෙම models වලට ලැබෙන 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 වල උපරිම සංඛ්යාවක් හෝ වටවල උපරිම සංඛ්යාවක් නියම කරන්නේ නැත.
- ඉල්ලීමේ body එක 32 MiB දක්වා විය හැකි අතර, ප්රතිඵල සහිත සංවාදය model එකේ context window එකට ගැළපිය යුතුය.
- ඉල්ලීමක
toolsඇති විට,shannon-1.6-lite,shannon-1.6-pro,shannon-2-liteසහshannon-2-proපෙරනිමිtemperature0.2 භාවිතා කරයි. වෙනත් අගයක් සැකසීමටtemperatureයවන්න. - සෑම වටයක්ම ඊට ම අයත් ඉල්ලීමකි: එය ඔබේ ශේෂයෙන් අඩු කරන අතර වෙනත් ඕනෑම ඉල්ලීමක් මෙන් flood protection වෙත ගණන් ගැනේ. සීමා සහ ශේෂය
දෝෂ
Tool call එකක් යනු 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 array එකක් නොවේ, නැතහොත් වෙනත් field එකක JSON type එක වැරදිය. |
413 | invalid_request_error | Failed to buffer the request body: … | ඉල්ලීමේ body එක 32 MiB ට වඩා විශාලය. දෝෂයේ code: "request_too_large" ඇත. |
Arguments ලියන්නේ model එකයි. ඕනෑම පිටත input එකක් පරීක්ෂා කරන ආකාරයටම, function එක ක්රියාත්මක කිරීමට පෙර ඒවා ඔබේ schema එකට එරෙහිව පරීක්ෂා කරන්න.
සත්යාපනය, ශේෂය සහ server දෝෂ සෑම ඉල්ලීමකටම මෙන්ම වේ. දෝෂ