Sejħiet ta' Funzjonijiet
Iddeskrivi l-funzjonijiet tiegħek fit-talba u l-mudell iwieġeb bis-sejħiet li jrid li jsiru. Il-kodiċi tiegħek iħaddimhom u jibgħat ir-riżultati lura: l-API tagħti lura sejħiet ta' tools u ma tħaddem l-ebda tool waħedha.
POST https://api.shannon-ai.com/v1/chat/completions
L-eżempji f'din il-paġna jużaw /v1/chat/completions. L-istess ċiklu jaħdem fuq /v1/responses u /v1/messages; fejn format jikteb xi ħaġa b'mod differenti, it-taqsimiet hawn taħt juru t-tlieta.
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"]
}
}
}]
}' L-ewwel tweġiba ma twieġibx il-mistoqsija. Titlob sejħa:
{
"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}
}
} Wara li tibgħat ir-riżultat, it-tweġiba li jmiss hija tweġiba ordinarja: message.content iżomm it-test u finish_reason huwa stop.
Iċ-ċiklu, pass pass
| Pass | Min | X'jiġri |
|---|---|---|
| 1 | Inti | Ibgħat messages flimkien ma' tools, il-lista ta' funzjonijiet li l-mudell jista' jitlob. |
| 2 | Mudell | It-tweġiba ġġorr tool_calls u finish_reason: "tool_calls". Kull sejħa tisemmi funzjoni u tagħti l-argumenti tagħha. |
| 3 | Inti | Parsja l-arguments ta' kull sejħa u ħaddem il-funzjoni tiegħek. |
| 4 | Inti | Żid il-messaġġ tal-assistent u messaġġ tool wieħed għal kull sejħa ma' messages, imbagħad ibgħat it-talba mill-ġdid bl-istess tools. |
| 5 | Mudell | Il-mudell iwieġeb bit-test b'finish_reason: "stop", jew jitlob aktar sejħiet. F'dak il-każ erġa' lura għall-pass 3. |
Talba waħda hija turn wieħed tal-mudell. L-API ma żżomm l-ebda konversazzjoni bejn it-talbiet u ma tistabbilixxi l-ebda numru ta' rounds: il-kodiċi tiegħek iżomm messages u jiddeċiedi meta jieqaf.
Kif tiddefinixxi tools
tools huwa array b'daħla waħda għal kull funzjoni. Kull mudell tal-katalgu jaċċettah; GET /v1/models jirrapporta capabilities.tools: true għal kull id.
| Qasam | Tip | Deskrizzjoni |
|---|---|---|
type | string | Dejjem function. |
function.name | string | L-isem li l-mudell juża meta jitlob din il-funzjoni. Meħtieġ. |
function.description | string | X'tagħmel il-funzjoni, b'lingwa sempliċi. |
function.parameters | object | L-argumenti bħala JSON Schema b'type: "object" fil-quċċata. Ara Keywords tal-schema hawn taħt. |
Kull endpoint għandu l-ikteb tiegħu ta' tool. Ibgħat dak li jagħmel parti mill-endpoint li tsejjaħ:
{
"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 jgħid jekk il-mudell jistax, jew għandux, isejjaħ tool. Jinqara biss flimkien ma' tools.
| Valur | Deskrizzjoni | Applikat minn |
|---|---|---|
"auto" | Il-mudell jiddeċiedi jekk iwieġebx bit-test jew jekk isejjaħx tool. Dan huwa d-default. | Il-mudelli kollha |
"required" | It-tweġiba tsejjaħ tool wieħed jew aktar. | Mudelli open-weight ospitati |
{"type": "function", "function": {"name": "get_weather"}} | It-tweġiba tsejjaħ din il-funzjoni. L-isem irid ikun waħda mill-funzjonijiet f'tools. Is-sejħiet għal funzjonijiet oħra jitħallew barra mit-tweġiba. | Mudelli open-weight ospitati |
Il-mudelli Shannon (shannon-*) jiddeċiedu f'kull talba, bħal b'auto.
B'required jew b'funzjoni msemmija, aqra finish_reason qabel taqra tool_calls. Meta l-mudell ma jipproduċi l-ebda sejħa, it-tweġiba hija tweġiba bit-test b'finish_reason: "stop".
| Tifsira | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Il-mudell jiddeċiedi | "auto" | "auto" | {"type": "auto"} |
| Sejjaħ tool wieħed jew aktar | "required" | "required" | {"type": "any"} |
| Sejjaħ funzjoni waħda msemmija | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Aċċettati għall-kompatibbiltà: tool_choice: "none" u parallel_tool_calls. Għal turn mingħajr sejħiet ta' tools, ibgħat it-talba mingħajr tools.
Sejħiet ta' tools fit-tweġiba
| Qasam | Tip | Deskrizzjoni |
|---|---|---|
finish_reason | string | tool_calls meta t-tweġiba ġġorr sejħa waħda jew aktar. |
message.tool_calls | array | Daħla waħda għal kull sejħa. Il-qasam huwa preżenti biss meta l-mudell talab sejħa. |
tool_calls[].id | string | call_ segwit minn 32 karattru eżadeċimali. Ibgħat lura bħala tool_call_id mar-riżultat. |
tool_calls[].type | string | Dejjem function. |
tool_calls[].function.name | string | Il-funzjoni li għandha taħdem. |
tool_calls[].function.arguments | string | L-argumenti bħala string JSON, "{}" meta ma jkun hemm l-ebda wieħed. Parsja qabel ma tużah. |
message.content | string | null | null meta t-tweġiba fiha biss sejħiet. Il-mudelli open-weight ospitati jistgħu jagħtu test maġenb is-sejħiet; il-mudelli Shannon jagħtu null. |
L-istess sejħa f'kull format. Fuq /v1/responses hija element function_call ta' output, b'arguments bħala string JSON. Fuq /v1/messages hija blokk tal-kontenut tool_use li l-input tiegħu huwa oġġett JSON, l-id tiegħu jibda b'toolu_, u stop_reason huwa 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"}
}
]
} Diversi sejħiet f'turn wieħed
Tweġiba tista' ġġorr diversi sejħiet. Ħaddem kull waħda minnhom u ibgħat riżultat wieħed għal kull sejħa, kull wieħed bit-tool_call_id tiegħu, fit-talba li jmiss.
Il-mudelli open-weight ospitati jagħtu lura kull sejħa distinta darba waħda: żewġ sejħiet bl-istess isem u bl-istess argumenti jaslu bħala waħda.
Sejħiet ta' tools fi stream
B'stream: true, sejħa tasal f'biċċa waħda: il-chunk iżomm l-string kompluta ta' arguments, għalhekk ma hemm l-ebda frammenti x'tgħaqqad. index jgħodd is-sejħiet tat-turn minn 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 | X'jasal |
|---|---|
/v1/chat/completions | chat.completion.chunk wieħed għal kull sejħa, bis-sejħa f'delta.tool_calls[0]. L-aħħar chunk għandu finish_reason: "tool_calls" u usage. |
/v1/responses | Għal kull sejħa: response.output_item.added (element function_call b'arguments vojta), response.function_call_arguments.delta (l-string kollha), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Għal kull sejħa: content_block_start (blokk tool_use b'input vojt), content_block_delta wieħed li l-input_json_delta.partial_json tiegħu huwa t-test sħiħ tal-argumenti, content_block_stop. message_delta imbagħad iġorr stop_reason: "tool_use". |
Fuq shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro u shannon-coder-1, talba fi stream li ġġorr tools twassal it-test tat-tweġiba tagħha f'delta content waħda fl-aħħar tat-turn. Streaming
Kif tibgħat ir-riżultati lura
It-tieni talba terġa' tibgħat il-konversazzjoni u żżid żewġ affarijiet: it-turn tal-assistent li talab is-sejħiet, u riżultat wieħed għal kull sejħa.
{
"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\"}"
}
]
}
]
} - Ibgħat it-turn tal-assistent lura kif irċevejtu, qabel ir-riżultati. Kull riżultat jiġi akkoppjat mas-sejħa tiegħu bl-id:
tool_call_idfuq/v1/chat/completions,call_idfuq/v1/responses,tool_use_idfuq/v1/messages. - Riżultat huwa test. Serjalizza oġġett f'string JSON għal
content(outputfuq/v1/responses). Fuq/v1/messagesil-contentta' blokktool_resulthuwa string jew lista ta' blokki tat-test. - Fit-turn tal-assistent,
function.argumentsjibqa' string JSON, eżattament kif wasal. - Il-konversazzjoni tista' tispiċċa b'riżultat ta' tool. Ma hemm bżonn l-ebda messaġġ ġdid tal-utent: il-mudell ikompli mir-riżultat.
- Meta l-funzjoni tiegħek tfalli, ibgħat il-falliment bħala t-test tar-riżultat. Il-mudell imbagħad jista' jirrapportah jew jitlob sejħa oħra.
Keywords tal-schema
parameters (input_schema fuq /v1/messages) huwa JSON Schema. Il-familja Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) u l-mudelli open-weight ospitati jirċevuh kif tibgħatu.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro u shannon-coder-1 jirċievu dan is-sottoinsieme, fit-tliet endpoints kollha:
| Trattament | Keywords |
|---|---|
| Jinqara kif intbagħat | Kull keyword li ma tissemmiex fir-ringieli hawn taħt, pereżempju type, properties, required, items, enum, description, minimum, maximum, anyOf u allOf, f'kull livell tal-schema. |
format | Jinqara għall-valuri int32, int64, float, double, byte, date, date-time u enum. |
oneOf | Jinqara bħala anyOf. |
| Mhux parti mill-schema li jirċievu dawn il-mudelli | $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 u exclusiveMaximum meta jkunu numri; valuri oħra ta' format. |
Imġiba u limiti
- L-API ma tistabbilixxi l-ebda numru massimu ta' tools u l-ebda numru massimu ta' rounds.
- Body ta' talba jista' jkun sa 32 MiB, u l-konversazzjoni bir-riżultati tagħha trid tidħol fit-tieqa tal-kuntest tal-mudell.
- Meta talba ġġorr
tools,shannon-1.6-lite,shannon-1.6-pro,shannon-2-liteushannon-2-projużawtemperaturedefault ta' 0.2. Ibgħattemperaturebiex tistabbilixxi valur ieħor. - Kull round huwa talba waħedha: tieħu mill-bilanċ tiegħek u tingħadd għall-protezzjoni mill-flood bħal kull talba oħra. Limiti u bilanċ
Żbalji
Sejħa ta' tool hija tweġiba normali b'status 200. Dawn l-iżbalji jirrigwardaw it-talba nnifisha:
| Status | Tip | Messaġġ | Meta |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model mhuwiex id mil-lista ppubblikata. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools mhuwiex array, jew qasam ieħor għandu tip JSON ħażin. |
413 | invalid_request_error | Failed to buffer the request body: … | Il-body tat-talba huwa akbar minn 32 MiB. L-iżball iġorr code: "request_too_large". |
Il-mudell jikteb l-argumenti. Iċċekkjahom mal-schema tiegħek qabel tħaddem il-funzjoni, bħalma tiċċekkja kwalunkwe input minn barra.
L-iżbalji ta' awtentikazzjoni, bilanċ u server huma l-istess bħal għal kull talba. Ġestjoni tal-iżbalji