Antso fiasa
Faritano ao amin'ny fangatahana ny function-nao dia mamaly ny model amin'ny antso tiany atao. Ny kaody-nao no mampandeha azy ireo ary mandefa ny valiny: ny API dia mamerina tool calls fa tsy mampandeha tool izy ihany.
POST https://api.shannon-ai.com/v1/chat/completions
Ny ohatra amin'ity pejy ity dia mampiasa ny /v1/chat/completions. Ny loop mitovy no mandeha amin'ny /v1/responses sy /v1/messages; raha misy zavatra tsy mitovy ny fanoratana amin'ny endrika iray, ny fizarana etsy ambany dia mampiseho ny telo.
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"]
}
}
}]
}' Ny valiny voalohany dia tsy mamaly ny fanontaniana. Mangataka antso izy:
{
"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}
}
} Rehefa alefanao ny valiny, ny valiny manaraka dia valiny mahazatra: ny message.content no misy ny soratra ary stop ny finish_reason.
Ny loop, dingana isan-dingana
| Dingana | Iza | Izay mitranga |
|---|---|---|
| 1 | Ianao | Alefaso ny messages miaraka amin'ny tools, ny lisitry ny function azon'ny model angatahana. |
| 2 | Model | Ny valiny dia mitondra tool_calls sy finish_reason: "tool_calls". Ny antso tsirairay dia manonona function ary manome ny arguments-ny. |
| 3 | Ianao | Parse-o ny arguments isaky ny antso ary ampandehano ny function-nao. |
| 4 | Ianao | Ampio ny hafatra assistant sy hafatra tool iray isaky ny antso ao amin'ny messages, avy eo alefaso indray ny fangatahana miaraka amin'ny tools mitovy. |
| 5 | Model | Mamaly amin'ny soratra miaraka amin'ny finish_reason: "stop" ny model, na mangataka antso hafa. Amin'izay dia miverena any amin'ny dingana 3. |
Fangatahana iray dia fihodinan'ny model iray. Ny API dia tsy mitahiry resaka eo anelanelan'ny fangatahana ary tsy mametraka isa fihodinana: ny kaody-nao no mitazona ny messages ary mamaritra rehefa hijanona.
Famaritana ny tools
Ny tools dia array misy iray isaky ny function. Ny model rehetra ao amin'ny catalogue dia mandray azy; ny GET /v1/models dia milaza capabilities.tools: true ho an'ny id rehetra.
| Saha | Karazana | Famaritana |
|---|---|---|
type | string | Foana function. |
function.name | string | Ny anarana ampiasain'ny model rehefa mangataka an'io function io. Ilaina. |
function.description | string | Izay ataon'ny function, amin'ny teny tsotra. |
function.parameters | object | Ny arguments ho JSON Schema misy type: "object" eo an-tampony. Jereo ny Keyword an'ny schema etsy ambany. |
Ny endpoint tsirairay dia manana fomba fanoratana tool manokana. Alefaso izay an'ilay endpoint antsoinao:
{
"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
Ny tool_choice dia milaza raha afaka, na tsy maintsy, miantso tool ny model. Vakiana miaraka amin'ny tools ihany izy.
| Sanda | Famaritana | Ampiharin'ny |
|---|---|---|
"auto" | Ny model no mamaritra raha hamaly amin'ny soratra na hiantso tool. Io no default. | Model rehetra |
"required" | Miantso tool iray farafahakeliny ny valiny. | Model open-weight hosted |
{"type": "function", "function": {"name": "get_weather"}} | Miantso an'io function io ny valiny. Tsy maintsy iray amin'ny function ao amin'ny tools ny anarana. Ny antso ny function hafa dia tsy ampidirina ao amin'ny valiny. | Model open-weight hosted |
Ny model Shannon (shannon-*) dia mamaritra isaky ny fangatahana, toy ny amin'ny auto.
Miaraka amin'ny required na function voatondro, vakio ny finish_reason alohan'ny tool_calls. Rehefa tsy mamokatra antso ny model, ny valiny dia valiny soratra miaraka amin'ny finish_reason: "stop".
| Dikany | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Ny model no mamaritra | "auto" | "auto" | {"type": "auto"} |
| Miantso tool iray farafahakeliny | "required" | "required" | {"type": "any"} |
| Miantso function iray voatondro | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Raisina ho an'ny compatibility: tool_choice: "none" sy parallel_tool_calls. Ho an'ny fihodinana tsy misy tool calls, alefaso ny fangatahana tsy misy tools.
Tool calls ao amin'ny valiny
| Saha | Karazana | Famaritana |
|---|---|---|
finish_reason | string | tool_calls rehefa mitondra antso iray farafahakeliny ny valiny. |
message.tool_calls | array | Iray isaky ny antso. Misy ny saha rehefa nangataka antso ny model ihany. |
tool_calls[].id | string | call_ arahin'ny tarehintsoratra hexadecimal 32. Averina miaraka amin'ny valiny ho tool_call_id. |
tool_calls[].type | string | Foana function. |
tool_calls[].function.name | string | Ny function tokony hotanterahina. |
tool_calls[].function.arguments | string | Ny arguments ho string JSON, "{}" raha tsy misy. Parse-o aloha vao ampiasaina. |
message.content | string | null | null rehefa antso ihany no ao amin'ny valiny. Ny model open-weight hosted dia afaka mamerina soratra miaraka amin'ny antso; ny model Shannon kosa mamerina null. |
Ny antso mitovy amin'ny endrika tsirairay. Amin'ny /v1/responses dia item function_call ao amin'ny output, miaraka amin'ny arguments ho string JSON. Amin'ny /v1/messages dia content block tool_use izay object JSON ny input-ny, manomboka amin'ny toolu_ ny id-ny, ary tool_use ny stop_reason.
{
"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"}
}
]
} Antso maromaro ao anatin'ny fihodinana iray
Ny valiny iray dia mety mitondra antso maromaro. Ampandehano daholo ary alefaso valiny iray isaky ny antso, samy manana ny tool_call_id-ny, ao amin'ny fangatahana manaraka.
Ny model open-weight hosted dia mamerina indray mandeha ny antso samy hafa: ny antso roa manana anarana sy arguments mitovy dia tonga ho iray.
Tool calls streamed
Miaraka amin'ny stream: true, ny antso dia tonga iray manontolo: ny chunk dia misy ny string arguments feno, ka tsy misy sombintsombiny hampiarahina. Ny index dia manisa ny antso ao amin'ny fihodinana manomboka amin'ny 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 | Izay tonga |
|---|---|
/v1/chat/completions | chat.completion.chunk iray isaky ny antso, miaraka amin'ny antso ao amin'ny delta.tool_calls[0]. Ny chunk farany dia manana finish_reason: "tool_calls" sy usage. |
/v1/responses | Isaky ny antso: response.output_item.added (item function_call misy arguments foana), response.function_call_arguments.delta (ny string manontolo), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Isaky ny antso: content_block_start (block tool_use misy input foana), content_block_delta iray izay ny input_json_delta.partial_json no soratra arguments manontolo, content_block_stop. Avy eo ny message_delta dia mitondra stop_reason: "tool_use". |
Amin'ny shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ary shannon-coder-1, ny fangatahana streamed mitondra tools dia manome ny soratra valiny ao anaty content delta iray amin'ny faran'ny fihodinana. Fandefasana mivantana
Fandefasana ny valiny
Ny fangatahana faharoa dia mamerina ny resaka ary manampy zavatra roa: ny fihodinan'ny assistant izay nangataka ny antso, sy valiny iray isaky ny antso.
{
"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\"}"
}
]
}
]
} - Alefaso indray ny fihodinan'ny assistant araka ny nahazoanao azy, alohan'ny valiny. Ny valiny tsirairay dia ampifanarahina amin'ny antso amin'ny alalan'ny id:
tool_call_idamin'ny/v1/chat/completions,call_idamin'ny/v1/responses,tool_use_idamin'ny/v1/messages. - Soratra ny valiny. Atao string JSON ny object ho an'ny
content(outputamin'ny/v1/responses). Amin'ny/v1/messagesdia string na lisitry ny text block nycontentan'ny blocktool_result. - Ao amin'ny fihodinan'ny assistant, ny
function.argumentsdia mijanona ho string JSON, araka ny nahatongavany. - Mety hifarana amin'ny valin'ny tool ny resaka. Tsy ilaina hafatra vaovao avy amin'ny mpampiasa: manohy avy amin'ny valiny ny model.
- Rehefa tsy nahomby ny function-nao, alefaso ho soratra valiny ny tsy fahombiazana. Afaka manambara izany na mangataka antso hafa ny model avy eo.
Keyword an'ny schema
Ny parameters (input_schema amin'ny /v1/messages) dia JSON Schema. Ny fianakavian'i Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) sy ny model open-weight hosted dia mandray azy araka ny nalefanao.
Ny shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ary shannon-coder-1 dia mandray ity ampahany ity, amin'ny endpoint telo rehetra:
| Fikarakarana | Keyword |
|---|---|
| Vakiana araka ny nalefa | Ny keyword rehetra tsy voatonona ao amin'ny andalana etsy ambany, ohatra type, properties, required, items, enum, description, minimum, maximum, anyOf ary allOf, amin'ny ambaratonga rehetra ao amin'ny schema. |
format | Vakiana ho an'ny sanda int32, int64, float, double, byte, date, date-time ary enum. |
oneOf | Vakiana ho anyOf. |
| Tsy anisan'ny schema raisin'ireto model ireto | $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 sy exclusiveMaximum rehefa isa izy ireo; sanda hafa amin'ny format. |
Fihetsika sy fetra
- Ny API dia tsy mametraka isa ambony indrindra ho an'ny tools na ho an'ny fihodinana.
- Ny body ny fangatahana dia hatramin'ny 32 MiB, ary ny resaka miaraka amin'ny valiny dia tsy maintsy tafiditra ao amin'ny context window an'ny model.
- Rehefa mitondra
toolsny fangatahana, nyshannon-1.6-lite,shannon-1.6-pro,shannon-2-litearyshannon-2-prodia mampiasatemperaturedefault 0.2. Alefaso nytemperatureraha te-hametraka sanda hafa. - Ny fihodinana tsirairay dia fangatahana mitokana: mamoaka avy amin'ny balance-nao izy ary ianarana amin'ny flood protection tahaka ny fangatahana hafa. Fetra sy balance
Hadisoana
Ny tool call dia valiny mahazatra miaraka amin'ny status 200. Ireto hadisoana ireto dia momba ny fangatahana mihitsy:
| Status | Karazana | Hafatra | Rahoviana |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | Tsy id ao amin'ny lisitra navoaka ny model. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Tsy array ny tools, na diso ny karazana JSON an'ny saha hafa. |
413 | invalid_request_error | Failed to buffer the request body: … | Lehibe noho ny 32 MiB ny body ny fangatahana. Ny hadisoana dia mitondra code: "request_too_large". |
Ny model no manoratra ny arguments. Hamarino amin'ny schema-nao izy ireo alohan'ny handefasana ny function, tahaka ny fanamarinana input rehetra avy any ivelany.
Ny fanamarinana, ny balance ary ny hadisoan'ny server dia mitovy amin'ny an'ny fangatahana rehetra. Fitantanana hadisoana