Funkcióhívás
Írd le a függvényeidet a kérésben, és a modell azokkal a hívásokkal válaszol, amelyeket végre akar hajtatni. A kódod futtatja őket, és visszaküldi az eredményeket: az API eszközhívásokat ad vissza, maga nem futtat eszközt.
POST https://api.shannon-ai.com/v1/chat/completions
Az oldal mintái a /v1/chat/completions végpontot használják. Ugyanez a ciklus fut a /v1/responses és a /v1/messages végponton is; ahol egy formátum másként írja le ugyanazt, az alábbi szakaszok mindhármat megmutatják.
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"]
}
}
}]
}' Az első válasz nem felel a kérdésre. Hívást kér:
{
"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}
}
} Miután elküldted az eredményt, a következő válasz egy közönséges felelet: a message.content a szöveget tartalmazza, a finish_reason pedig stop.
A ciklus lépésről lépésre
| Lépés | Ki | Mi történik |
|---|---|---|
| 1 | Te | Küldd el a messages tömböt a tools mezővel együtt, amely azokat a függvényeket sorolja fel, amelyeket a modell kérhet. |
| 2 | Modell | A válasz tool_calls mezőt és finish_reason: "tool_calls" értéket hordoz. Minden hívás megnevez egy függvényt, és megadja az argumentumait. |
| 3 | Te | Értelmezd (parse) minden hívás arguments mezőjét, és futtasd a függvényedet. |
| 4 | Te | Fűzd hozzá a messages tömbhöz az assistant üzenetet és hívásonként egy tool üzenetet, majd küldd el újra a kérést ugyanazzal a tools mezővel. |
| 5 | Modell | A modell szöveggel válaszol finish_reason: "stop" értékkel, vagy további hívásokat kér. Ez utóbbi esetben menj vissza a 3. lépéshez. |
Egy kérés egy modellforduló. Az API nem tart fenn beszélgetést a kérések között, és nem szab meg körszámot: a kódod tárolja a messages tömböt, és ő dönti el, mikor álljon le.
Eszközök megadása
A tools egy tömb, függvényenként egy elemmel. A katalógus minden modellje elfogadja; a GET /v1/models minden azonosítónál capabilities.tools: true értéket jelent.
| Mező | Típus | Leírás |
|---|---|---|
type | string | Mindig function. |
function.name | string | A név, amelyet a modell használ, amikor ezt a függvényt kéri. Kötelező. |
function.description | string | Mit csinál a függvény, közérthető nyelven. |
function.parameters | object | Az argumentumok JSON Schema formában, a tetején type: "object" értékkel. Lásd lejjebb: Séma-kulcsszavak. |
Minden végpontnak saját írásmódja van az eszközre. Azt küldd, amelyik a hívott végponthoz tartozik:
{
"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
A tool_choice megadja, hogy a modell hívhat-e eszközt, vagy hívnia kell-e. Csak a tools mellett érvényes.
| Érték | Leírás | Alkalmazza |
|---|---|---|
"auto" | A modell dönti el, hogy szöveggel válaszol, vagy eszközt hív. Ez az alapértelmezés. | Minden modell |
"required" | A válasz legalább egy eszközt hív. | Hosztolt nyílt súlyú modellek |
{"type": "function", "function": {"name": "get_weather"}} | A válasz ezt a függvényt hívja. A névnek a tools függvényei közül valónak kell lennie. A többi függvény hívásai kimaradnak a válaszból. | Hosztolt nyílt súlyú modellek |
A Shannon modellek (shannon-*) minden kérésnél maguk döntenek, mint auto esetén.
required vagy megnevezett függvény esetén a tool_calls olvasása előtt nézd meg a finish_reason értékét. Ha a modell nem hoz létre hívást, a válasz szöveges felelet finish_reason: "stop" értékkel.
| Jelentés | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| A modell dönt | "auto" | "auto" | {"type": "auto"} |
| Legalább egy eszköz hívása | "required" | "required" | {"type": "any"} |
| Egy megnevezett függvény hívása | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Kompatibilitás miatt elfogadott: tool_choice: "none" és parallel_tool_calls. Eszközhívás nélküli fordulóhoz küldd a kérést tools nélkül.
Eszközhívások a válaszban
| Mező | Típus | Leírás |
|---|---|---|
finish_reason | string | tool_calls, ha a válasz legalább egy hívást tartalmaz. |
message.tool_calls | array | Hívásonként egy elem. A mező csak akkor szerepel, ha a modell hívást kért. |
tool_calls[].id | string | A call_ után 32 hexadecimális karakter áll. Az eredménnyel együtt küldd vissza tool_call_id néven. |
tool_calls[].type | string | Mindig function. |
tool_calls[].function.name | string | A futtatandó függvény. |
tool_calls[].function.arguments | string | Az argumentumok JSON-stringként, "{}", ha nincsenek. Használat előtt dolgozd fel. |
message.content | string | null | null, ha a válasz csak hívásokat tartalmaz. A hosztolt nyílt súlyú modellek a hívások mellett szöveget is visszaadhatnak; a Shannon modellek null értéket adnak. |
Ugyanaz a hívás minden formátumban. A /v1/responses végponton az output egy function_call eleme, az arguments pedig JSON-string. A /v1/messages végponton tool_use tartalmi blokk, amelynek input mezője JSON-objektum, az id értéke toolu_ előtaggal kezdődik, a stop_reason pedig 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"}
}
]
} Több hívás egy fordulóban
Egy válasz több hívást is hordozhat. Futtasd mindet, és a következő kérésben küldj hívásonként egy eredményt, mindegyiket a saját tool_call_id értékével.
A hosztolt nyílt súlyú modellek minden különböző hívást egyszer adnak vissza: két azonos nevű és azonos argumentumú hívás egyként érkezik.
Streamelt eszközhívások
stream: true esetén a hívás egy darabban érkezik: a chunk a teljes arguments stringet tartalmazza, így nincsenek összefűzendő töredékek. Az index a forduló hívásait számolja 0-tól.
{
"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
}
]
} | Végpont | Mi érkezik |
|---|---|
/v1/chat/completions | Hívásonként egy chat.completion.chunk, a hívással a delta.tool_calls[0] mezőben. Az utolsó chunk finish_reason: "tool_calls" értéket és usage mezőt tartalmaz. |
/v1/responses | Hívásonként: response.output_item.added (üres arguments mezős function_call elem), response.function_call_arguments.delta (a teljes string), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Hívásonként: content_block_start (üres input mezős tool_use blokk), egy content_block_delta, amelynek input_json_delta.partial_json mezője a teljes argumentumszöveg, content_block_stop. Ezután a message_delta stop_reason: "tool_use" értéket hordoz. |
A shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro és shannon-coder-1 modellen az a streamelt kérés, amely tools mezőt tartalmaz, a válaszszöveget egyetlen content deltában adja a forduló végén. Streaming
Eredmények visszaküldése
A második kérés megismétli a beszélgetést, és két dolgot ad hozzá: az assistant fordulót, amely a hívásokat kérte, és hívásonként egy eredményt.
{
"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\"}"
}
]
}
]
} - Az assistant fordulót úgy küldd vissza, ahogy kaptad, az eredmények előtt. Minden eredményt azonosító párosít a hívásához:
tool_call_ida/v1/chat/completions,call_ida/v1/responses,tool_use_ida/v1/messagesvégponton. - Az eredmény szöveg. Szerializálj egy objektumot JSON-stringgé a
contentmezőhöz (a/v1/responsesvégponton azoutputmezőhöz). A/v1/messagesvégponton atool_resultblokkcontentmezője string vagy szövegblokkok listája. - Az assistant fordulóban a
function.argumentsJSON-string marad, pontosan úgy, ahogy megérkezett. - A beszélgetés végződhet eszközeredménnyel. Új user üzenet nem kell: a modell az eredménytől folytatja.
- Ha a függvényed hibázik, a hibát küldd el az eredmény szövegeként. A modell ezután jelezheti, vagy másik hívást kérhet.
Séma-kulcsszavak
A parameters (a /v1/messages végponton input_schema) egy JSON Schema. A Shannon 3 család (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) és a hosztolt nyílt súlyú modellek úgy kapják meg, ahogy küldöd.
A shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro és shannon-coder-1 ezt a részhalmazt kapja meg, mindhárom végponton:
| Kezelés | Kulcsszavak |
|---|---|
| Úgy olvassa, ahogy küldted | Minden kulcsszó, amelyet az alábbi sorok nem neveznek meg, például type, properties, required, items, enum, description, minimum, maximum, anyOf és allOf, a séma minden szintjén. |
format | Az int32, int64, float, double, byte, date, date-time és enum értékeket olvassa. |
oneOf | anyOf szerint olvassa. |
| Nem része annak a sémának, amelyet ezek a modellek kapnak | $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; az exclusiveMinimum és az exclusiveMaximum, ha számok; a format egyéb értékei. |
Viselkedés és korlátok
- Az API nem szab meg legnagyobb eszközszámot, sem legnagyobb körszámot.
- A kérés törzse legfeljebb 32 MiB lehet, és az eredményekkel együtt a beszélgetésnek bele kell férnie a modell kontextusablakába.
- Ha a kérés
toolsmezőt tartalmaz, ashannon-1.6-lite,shannon-1.6-pro,shannon-2-liteésshannon-2-pro0.2 alapértelmezetttemperatureértéket használ. Más érték beállításához küldjtemperaturemezőt. - Minden kör külön kérés: az egyenlegedből vonódik, és mint bármely más kérés, beleszámít a flood protection korlátba. Korlátok és egyenleg
Hibák
Az eszközhívás rendes válasz 200-as státusszal. Ezek a hibák magát a kérést érintik:
| Státusz | Típus | Üzenet | Mikor |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | A model nem szerepel a közzétett listában. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | A tools nem tömb, vagy egy másik mező JSON-típusa hibás. |
413 | invalid_request_error | Failed to buffer the request body: … | A kérés törzse nagyobb 32 MiB-nál. A hiba code: "request_too_large" értéket hordoz. |
Az argumentumokat a modell írja. Ellenőrizd őket a sémád alapján, mielőtt futtatod a függvényt, mint bármilyen külső bemenetet.
A hitelesítési, egyenleg- és szerverhibák ugyanazok, mint minden kérésnél. Hibakezelés