Funtzio-deiak
Deskribatu zure funtzioak eskaeran eta modeloak egin nahi dituen deiekin erantzungo du. Zure kodeak exekutatzen ditu eta emaitzak bidaltzen ditu berriro: API-ak tresna-deiak itzultzen ditu eta ez du tresnarik berak exekutatzen.
POST https://api.shannon-ai.com/v1/chat/completions
Orrialde honetako laginek /v1/chat/completions erabiltzen dute. Begizta bera /v1/responses eta /v1/messages endpoint-etan ere exekutatzen da; formatu batek zerbait modu desberdinean idazten duenean, beheko ataletan hiru formak erakusten dira.
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"]
}
}
}]
}' Lehen erantzunak ez du galderari erantzuten. Dei bat eskatzen du:
{
"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}
}
} Emaitza bidali ondoren, hurrengo erantzuna ohiko erantzun bat da: message.content-ek testua du eta finish_reason stop da.
Begizta, urratsez urrats
| Urratsa | Nork | Zer gertatzen den |
|---|---|---|
| 1 | Zuk | Bidali messages eta tools batera, modeloak eska ditzakeen funtzioen zerrenda. |
| 2 | Modeloa | Erantzunak tool_calls eta finish_reason: "tool_calls" ditu. Dei bakoitzak funtzio bat izendatzen du eta bere argumentuak ematen ditu. |
| 3 | Zuk | Aztertu dei bakoitzaren arguments eta exekutatu zure funtzioa. |
| 4 | Zuk | Gehitu assistant mezua eta tool mezu bat dei bakoitzeko messages-era, eta bidali eskaera berriro tools berberekin. |
| 5 | Modeloa | Modeloak testuan erantzuten du finish_reason: "stop" erabiliz, edo dei gehiago eskatzen ditu. Kasu horretan itzuli 3. urratsera. |
Eskaera bat modelo-txanda bat da. API-ak ez du elkarrizketarik gordetzen eskaeren artean eta ez du itzuli-kopururik ezartzen: zure kodeak messages gordetzen du eta noiz gelditu erabakitzen du.
Tresnak definitzea
tools array bat da, funtzio bakoitzeko sarrera batekin. Katalogoko modelo guztiek onartzen dute; GET /v1/models-ek capabilities.tools: true jakinarazten du id guztientzat.
| Eremua | Mota | Deskribapena |
|---|---|---|
type | string | Beti function. |
function.name | string | Modeloak funtzio hau eskatzean erabiltzen duen izena. Beharrezkoa. |
function.description | string | Funtzioak zer egiten duen, hizkuntza arruntean. |
function.parameters | object | Argumentuak JSON Schema gisa, goian type: "object" duela. Ikus beheko Eskema-gako-hitzak. |
Endpoint bakoitzak bere idazkera du tresna baterako. Bidali deitzen duzun endpoint-ari dagokiona:
{
"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-k esaten du modeloak tresna bati dei diezaiokeen edo deitu behar duen. tools-ekin batera bakarrik irakurtzen da.
| Balioa | Deskribapena | Aplikatzen duena |
|---|---|---|
"auto" | Modeloak erabakitzen du testuan erantzun ala tresna bati deitu. Hau da lehenetsia. | Modelo guztiak |
"required" | Erantzunak tresna bati gutxienez deitzen dio. | Pisu irekiko modelo ostatatuak |
{"type": "function", "function": {"name": "get_weather"}} | Erantzunak funtzio horri deitzen dio. Izenak tools-eko funtzioetako bat izan behar du. Beste funtzioei egindako deiak erantzunetik kanpo uzten dira. | Pisu irekiko modelo ostatatuak |
Shannon modeloek (shannon-*) eskaera bakoitzean erabakitzen dute, auto bezala.
required edo izendatutako funtzio batekin, irakurri finish_reason tool_calls irakurri aurretik. Modeloak deirik sortzen ez duenean, erantzuna testu-erantzun bat da, finish_reason: "stop" duena.
| Esanahia | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Modeloak erabakitzen du | "auto" | "auto" | {"type": "auto"} |
| Tresna bati gutxienez deitu | "required" | "required" | {"type": "any"} |
| Funtzio izendatu bati deitu | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Bateragarritasunerako onartuak: tool_choice: "none" eta parallel_tool_calls. Tresna-deirik gabeko txanda baterako, bidali eskaera tools gabe.
Tresna-deiak erantzunean
| Eremua | Mota | Deskribapena |
|---|---|---|
finish_reason | string | tool_calls erantzunak dei bat gutxienez daramanean. |
message.tool_calls | array | Sarrera bat dei bakoitzeko. Eremua modeloak dei bat eskatu duenean bakarrik dago. |
tool_calls[].id | string | call_ eta ondoren 32 karaktere hexadezimal. Bidali berriro tool_call_id gisa emaitzarekin. |
tool_calls[].type | string | Beti function. |
tool_calls[].function.name | string | Exekutatu beharreko funtzioa. |
tool_calls[].function.arguments | string | Argumentuak JSON kate gisa, "{}" batere ez dagoenean. Aztertu erabili aurretik. |
message.content | string | null | null erantzunak deiak bakarrik dituenean. Pisu irekiko modelo ostatatuek testua itzul dezakete deien ondoan; Shannon modeloek null itzultzen dute. |
Dei bera formatu bakoitzean. /v1/responses endpoint-ean output-eko function_call elementu bat da, arguments JSON kate gisa duela. /v1/messages endpoint-ean tool_use eduki-bloke bat da, bere input JSON objektu bat dela, bere id toolu_ hasten dela, eta stop_reason tool_use dela.
{
"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"}
}
]
} Dei anitz txanda batean
Erantzun batek dei anitz eraman ditzake. Exekutatu guztiak eta bidali emaitza bat dei bakoitzeko, bakoitza bere tool_call_id-rekin, hurrengo eskaeran.
Pisu irekiko modelo ostatatuek dei bereizi bakoitza behin itzultzen dute: izen bera eta argumentu berak dituzten bi dei bat bezala iristen dira.
Stream bidezko tresna-deiak
stream: true erabiliz, dei bat zati bakarrean iristen da: chunk-ak arguments kate osoa du, beraz ez dago elkartzeko zatirik. index-ek txandako deiak 0tik kontatzen ditu.
{
"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-a | Zer iristen den |
|---|---|
/v1/chat/completions | chat.completion.chunk bat dei bakoitzeko, deia delta.tool_calls[0]-n dela. Azken chunk-ak finish_reason: "tool_calls" eta usage ditu. |
/v1/responses | Dei bakoitzeko: response.output_item.added (function_call elementu bat arguments hutsarekin), response.function_call_arguments.delta (kate osoa), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Dei bakoitzeko: content_block_start (tool_use bloke bat input hutsarekin), content_block_delta bat non input_json_delta.partial_json argumentuen testu osoa den, content_block_stop. message_delta-k orduan stop_reason: "tool_use" darama. |
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro eta shannon-coder-1 modeloetan, tools darabilen stream bidezko eskaerak bere erantzun-testua content delta batean ematen du txandaren amaieran. Streaminga
Emaitzak berriro bidaltzea
Bigarren eskaerak elkarrizketa errepikatzen du eta bi gauza gehitzen ditu: deiak eskatu zituen assistant txanda, eta emaitza bat dei bakoitzeko.
{
"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\"}"
}
]
}
]
} - Bidali assistant txanda berriro jaso zenuen bezala, emaitzen aurretik. Emaitza bakoitza bere deiarekin id bidez lotzen da:
tool_call_id/v1/chat/completionsendpoint-ean,call_id/v1/responsesendpoint-ean,tool_use_id/v1/messagesendpoint-ean. - Emaitza testu bat da. Serializatu objektu bat JSON kate batera
content-erako (output/v1/responsesendpoint-ean)./v1/messagesendpoint-eantool_resultbloke batencontentkate bat da edo testu-blokeen zerrenda bat. - Assistant txandan,
function.argumentsJSON kate izaten jarraitzen du, iritsi zen bezala. - Elkarrizketa tresna-emaitza batekin amaitu daiteke. Ez da erabiltzaile-mezu berririk behar: modeloak emaitzatik jarraitzen du.
- Zure funtzioak huts egiten duenean, bidali hutsegitea emaitza-testu gisa. Modeloak orduan jakinaraz dezake edo beste dei bat eska dezake.
Eskema-gako-hitzak
parameters (input_schema /v1/messages endpoint-ean) JSON Schema bat da. Shannon 3 familiak (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) eta pisu irekiko modelo ostatatuek bidaltzen duzun bezala jasotzen dute.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro eta shannon-coder-1 modeloek azpimultzo hau jasotzen dute, hiru endpoint-etan:
| Tratamendua | Gako-hitzak |
|---|---|
| Bidalitako bezala irakurria | Beheko errenkadetan izendatzen ez den gako-hitz oro, adibidez type, properties, required, items, enum, description, minimum, maximum, anyOf eta allOf, eskemaren maila guztietan. |
format | int32, int64, float, double, byte, date, date-time eta enum balioetarako irakurtzen da. |
oneOf | anyOf gisa irakurtzen da. |
| Ez da modelo hauek jasotzen duten eskemaren parte | $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 eta exclusiveMaximum zenbakiak direnean; format-en beste balioak. |
Portaera eta mugak
- API-ak ez du tresna-kopuru maximorik ezartzen, ez itzuli-kopuru maximorik.
- Eskaera-gorputzak 32 MiB arte izan dezake, eta elkarrizketak bere emaitzekin modeloaren testuinguru-leihoan sartu behar du.
- Eskaera batek
toolsdarabilenean,shannon-1.6-lite,shannon-1.6-pro,shannon-2-liteetashannon-2-promodeloek 0.2 lehenetsikotemperatureerabiltzen dute. Bidalitemperaturebeste balio bat ezartzeko. - Itzuli bakoitza eskaera propio bat da: zure saldotik hartzen du eta flood protection-eko kontaketan sartzen da beste edozein eskaera bezala. Mugak eta saldoa
Erroreak
Tresna-dei bat 200 egoerako ohiko erantzun bat da. Errore hauek eskaerari berari buruzkoak dira:
| Egoera | Mota | Mezua | Noiz |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model ez da argitaratutako zerrendako id bat. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools ez da array bat, edo beste eremu batek JSON mota okerra du. |
413 | invalid_request_error | Failed to buffer the request body: … | Eskaera-gorputza 32 MiB baino handiagoa da. Erroreak code: "request_too_large" darama. |
Modeloak idazten ditu argumentuak. Egiaztatu zure eskemaren aurka funtzioa exekutatu aurretik, kanpoko edozein sarrera egiaztatuko zenukeen bezala.
Autentifikazio-, saldo- eta zerbitzari-erroreak eskaera guztietan bezalakoak dira. Errore‑kudeaketa