Mekhosi ya mesebetsi
Hlalosa li-function tsa hau kopong mme model e araba ka likopo tseo e batlang li etsoa. Code ea hau e li etsa mme e romela liphetho hape: API e khutlisa likopo tsa tool mme ha e etse tool ka boeona.
POST https://api.shannon-ai.com/v1/chat/completions
Mehlala leqepheng lena e sebelisa /v1/chat/completions. Loop e tšoanang e sebetsa ho /v1/responses le /v1/messages; moo sebopeho se ngolang ntho ka tsela e fapaneng, likarolo tse ka tlase li bontša tse tharo kaofela.
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"]
}
}
}]
}' Karabo ea pele ha e arabe potso. E kopa kopo ea tool:
{
"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 mor'a hore u romele sephetho, karabo e latelang ke karabo e tloaelehileng: message.content e na le mongolo mme finish_reason ke stop.
Loop, mohato ka mohato
| Mohato | Mang | Se etsahalang |
|---|---|---|
| 1 | Uena | Romela messages hammoho le tools, lenane la li-function tseo model e ka li kopang. |
| 2 | Model | Karabo e nka tool_calls le finish_reason: "tool_calls". Kopo e 'ngoe le e 'ngoe e reha function mme e fana ka li-argument tsa eona. |
| 3 | Uena | Parse arguments ea kopo e 'ngoe le e 'ngoe mme u etse function ea hau. |
| 4 | Uena | Eketsa molaetsa oa assistant le molaetsa o le mong oa tool ka kopo ho messages, ebe u romela kopo hape le tools tse tšoanang. |
| 5 | Model | Model e araba ka mongolo le finish_reason: "stop", kapa e kopa likopo tse ling. Maemong ao khutlela ho mohato oa 3. |
Kopo e le 'ngoe ke turn e le 'ngoe ea model. API ha e boloke moqoqo pakeng tsa likopo mme ha e beha palo ea li-round: code ea hau e tšoara messages mme e etsa qeto ea hore na e ema neng.
Ho hlalosa lisebelisoa
tools ke array e nang le entry e le 'ngoe ka function. Model e 'ngoe le e 'ngoe ea catalogue e e amohela; GET /v1/models e tlaleha capabilities.tools: true bakeng sa id e 'ngoe le e 'ngoe.
| Field | Mofuta | Tlhaloso |
|---|---|---|
type | string | Kamehla ke function. |
function.name | string | Lebitso leo model e le sebelisang ha e kopa function ena. E hlokahala. |
function.description | string | Seo function e se etsang, ka puo e bonolo. |
function.parameters | object | Li-argument e le JSON Schema e nang le type: "object" holimo. Bona Mantsoe a bohlokoa a schema ka tlase. |
Endpoint e 'ngoe le e 'ngoe e na le mokhoa oa eona oa ho ngola tool. Romela eo e leng ea endpoint eo u e bitsang:
{
"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 e re ke hore na model e ka bitsa tool, kapa e tlameha ho e bitsa. E baloa feela hammoho le tools.
| Boleng | Tlhaloso | E sebelisoa ke |
|---|---|---|
"auto" | Model e iketsetsa qeto ea hore na e arabe ka mongolo kapa e bitse tool. Ena ke default. | Li-model tsohle |
"required" | Karabo e bitsa bonyane tool e le 'ngoe. | Li-model tse hosted tsa open-weight |
{"type": "function", "function": {"name": "get_weather"}} | Karabo e bitsa function ena. Lebitso le tlameha ho ba le leng la li-function tse ho tools. Likopo tsa li-function tse ling li siuoa karabong. | Li-model tse hosted tsa open-weight |
Li-model tsa Shannon (shannon-*) li iketsetsa qeto kopong e 'ngoe le e 'ngoe, joalo ka ka auto.
Ka required kapa function e rehiloeng, bala finish_reason pele u bala tool_calls. Ha model e sa hlahise kopo, karabo ke karabo ea mongolo e nang le finish_reason: "stop".
| Moelelo | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Model e iketsetsa qeto | "auto" | "auto" | {"type": "auto"} |
| Bitsa bonyane tool e le 'ngoe | "required" | "required" | {"type": "any"} |
| Bitsa function e le 'ngoe e rehiloeng | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Li amohelwa bakeng sa compatibility: tool_choice: "none" le parallel_tool_calls. Bakeng sa turn e se nang likopo tsa tool, romela kopo ntle le tools.
Likopo tsa tool karabong
| Field | Mofuta | Tlhaloso |
|---|---|---|
finish_reason | string | tool_calls ha karabo e nka bonyane kopo e le 'ngoe. |
message.tool_calls | array | Entry e le 'ngoe ka kopo. Field e teng feela ha model e kopile kopo. |
tool_calls[].id | string | call_ e latelwa ke litlhaku tse 32 tsa hexadecimal. E khutlisetse e le tool_call_id hammoho le sephetho. |
tool_calls[].type | string | Kamehla ke function. |
tool_calls[].function.name | string | Function e lokelang ho etsoa. |
tool_calls[].function.arguments | string | Li-argument e le string ea JSON, "{}" ha ho e 'ngoe. E parse pele u e sebelisa. |
message.content | string | null | null ha karabo e na le likopo feela. Li-model tse hosted tsa open-weight li ka khutlisa mongolo haufi le likopo; li-model tsa Shannon li khutlisa null. |
Kopo e tšoanang sebopeho se seng le se seng. Ho /v1/responses ke ntho ea function_call ea output, e nang le arguments e le string ea JSON. Ho /v1/messages ke content block ea tool_use eo input ea eona e leng ntho ea JSON, id ea eona e qala ka toolu_, mme stop_reason ke 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"}
}
]
} Likopo tse ngata turn e le 'ngoe
Karabo e ka nka likopo tse ngata. Etsa e 'ngoe le e 'ngoe ea tsona mme u romele sephetho se le seng ka kopo, e 'ngoe le e 'ngoe e na le tool_call_id ea eona, kopong e latelang.
Li-model tse hosted tsa open-weight li khutlisa kopo e 'ngoe le e 'ngoe e ikhethang hang feela: likopo tse peli tse nang le lebitso le li-argument tse tšoanang li fihla e le e le 'ngoe.
Likopo tsa tool tsa streaming
Ka stream: true, kopo e fihla e le sekhechana se le seng: chunk e na le string eohle ea arguments, kahoo ha ho likhechana tseo u lokelang ho li kopanya. index e bala likopo tsa turn ho tloha ho 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 | Seo se fihlang |
|---|---|
/v1/chat/completions | chat.completion.chunk e le 'ngoe ka kopo, e nang le kopo ho delta.tool_calls[0]. Chunk ea ho qetela e na le finish_reason: "tool_calls" le usage. |
/v1/responses | Ka kopo: response.output_item.added (ntho ea function_call e nang le arguments e se nang letho), response.function_call_arguments.delta (string eohle), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Ka kopo: content_block_start (block ea tool_use e nang le input e se nang letho), content_block_delta e le 'ngoe eo input_json_delta.partial_json ea eona e leng mongolo oohle oa li-argument, content_block_stop. Ebe message_delta e nka stop_reason: "tool_use". |
Ho shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro le shannon-coder-1, kopo ea streaming e nang le tools e fana ka mongolo oa karabo ho content delta e le 'ngoe qetellong ea turn. Phallela
Ho romela liphetho hape
Kopo ea bobeli e pheta moqoqo mme e eketsa lintho tse peli: turn ea assistant e kopileng likopo, le sephetho se le seng ka kopo.
{
"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\"}"
}
]
}
]
} - Romela turn ea assistant hape joalo ka ha u e fumane, pele ho liphetho. Sephetho se seng le se seng se amanngoa le kopo ea sona ka id:
tool_call_idho/v1/chat/completions,call_idho/v1/responses,tool_use_idho/v1/messages. - Sephetho ke mongolo. Fetolela ntho ho string ea JSON bakeng sa
content(outputho/v1/responses). Ho/v1/messagescontentea block eatool_resultke string kapa lenane la li-block tsa mongolo. - Turn-ng ea assistant,
function.argumentse lula e le string ea JSON, hantle joalo ka ha e fihlile. - Moqoqo o ka fela ka sephetho sa tool. Ha ho hlokahale molaetsa o mocha oa user: model e tsoela pele ho tloha sephetho.
- Ha function ea hau e hloleha, romela phoso e le mongolo oa sephetho. Model e ka e tlaleha kapa ea kopa kopo e 'ngoe.
Mantsoe a bohlokoa a schema
parameters (input_schema ho /v1/messages) ke JSON Schema. Lelapa la Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) le li-model tse hosted tsa open-weight li e amohela joalo ka ha u e romela.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro le shannon-coder-1 li amohela subset ena, ho li-endpoint tse tharo tsohle:
| Tsela ea ho sebetsana le eona | Mantsoe a bohlokoa |
|---|---|
| E baloa joalo ka ha e rometsoe | Lentsoe le leng le le leng le sa rehoang mela e ka tlase, mohlala type, properties, required, items, enum, description, minimum, maximum, anyOf le allOf, boemong bo bong le bo bong ba schema. |
format | E baloa bakeng sa litekanyo int32, int64, float, double, byte, date, date-time le enum. |
oneOf | E baloa e le anyOf. |
| Hase karolo ea schema eo li-model tsena li e amohelang | $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 le exclusiveMaximum ha e le linomoro; litekanyo tse ling tsa format. |
Boitšoaro le meeli
- API ha e beha palo e phahameng ea lisebelisoa kapa palo e phahameng ea li-round.
- Body ea kopo e ka ba 32 MiB, mme moqoqo le liphetho tsa oona o tlameha ho kena ho context window ea model.
- Ha kopo e na le
tools,shannon-1.6-lite,shannon-1.6-pro,shannon-2-liteleshannon-2-proli sebelisatemperatureea default ea 0.2. Romelatemperatureho beha boleng bo bong. - Round e 'ngoe le e 'ngoe ke kopo ea eona: e ntša ho balance ea hau mme e baloa ho flood protection joalo ka kopo e 'ngoe le e 'ngoe. Meeli le balance
Liphoso
Kopo ea tool ke karabo e tloaelehileng e nang le boemo ba 200. Liphoso tsena li amana le kopo ka boeona:
| Boemo | Mofuta | Molaetsa | Neng |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model hase id ea lenane le phatlalalitsoeng. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools hase array, kapa field e ngoe e na le mofuta o fosahetseng oa JSON. |
413 | invalid_request_error | Failed to buffer the request body: … | Body ea kopo e kholo ho feta 32 MiB. Phoso e na le code: "request_too_large". |
Model e ngola li-argument. Li hlahlobe ka schema ea hau pele u etsa function, joalo ka ha u ka hlahloba input efe kapa efe ea ka ntle.
Liphoso tsa netefatso, balance le server li tšoana le tsa kopo e 'ngoe le e 'ngoe. Diphoso