Funkcijų kvietimas
Apibūdinkite savo funkcijas užklausoje, o modelis atsakys kreipiniais, kuriuos nori atlikti. Jūsų kodas juos vykdo ir grąžina rezultatus: API grąžina įrankių kreipinius ir pats įrankio nevykdo.
POST https://api.shannon-ai.com/v1/chat/completions
Šio puslapio pavyzdžiuose naudojamas /v1/chat/completions. Tas pats ciklas veikia kelyje /v1/responses ir /v1/messages; kur formatai kažką užrašo kitaip, toliau pateikiami visi trys variantai.
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"]
}
}
}]
}' Pirmasis atsakymas į klausimą neatsako. Jame prašoma kreipinio:
{
"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}
}
} Išsiuntus rezultatą, kitas atsakymas yra įprastas atsakymas: message.content talpina tekstą, o finish_reason yra stop.
Ciklas žingsnis po žingsnio
| Žingsnis | Kas | Kas vyksta |
|---|---|---|
| 1 | Jūs | Siųskite messages kartu su tools – funkcijų, kurių modelis gali prašyti, sąrašu. |
| 2 | Modelis | Atsakyme yra tool_calls ir finish_reason: "tool_calls". Kiekvienas kreipinys nurodo funkciją ir pateikia jos argumentus. |
| 3 | Jūs | Išanalizuokite kiekvieno kreipinio arguments ir vykdykite savo funkciją. |
| 4 | Jūs | Prie messages pridėkite asistento pranešimą ir po vieną tool pranešimą kiekvienam kreipiniui, tada vėl siųskite užklausą su tais pačiais tools. |
| 5 | Modelis | Modelis atsako tekstu su finish_reason: "stop" arba prašo daugiau kreipinių. Tuo atveju grįžkite prie 3 žingsnio. |
Viena užklausa yra vienas modelio ėjimas. API tarp užklausų pokalbio nesaugo ir ratų skaičiaus nenustato: messages laikote jūs ir jūs nusprendžiate, kada sustoti.
Įrankių apibrėžimas
tools yra masyvas, kuriame po vieną įrašą kiekvienai funkcijai. Jį priima kiekvienas katalogo modelis; GET /v1/models kiekvienam id nurodo capabilities.tools: true.
| Laukas | Tipas | Aprašymas |
|---|---|---|
type | string | Visada function. |
function.name | string | Pavadinimas, kurį modelis naudoja prašydamas šios funkcijos. Privalomas. |
function.description | string | Ką funkcija daro, paprasta kalba. |
function.parameters | object | Argumentai kaip JSON Schema, viršuje su type: "object". Žr. toliau Schemos raktažodžiai. |
Kiekvienas galinis taškas turi savo įrankio užrašymo būdą. Siųskite tą, kuris priklauso jūsų kviečiamam galiniam taškui:
{
"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 nurodo, ar modelis gali, ar privalo iškviesti įrankį. Jis skaitomas tik kartu su tools.
| Reikšmė | Aprašymas | Taiko |
|---|---|---|
"auto" | Modelis pats nusprendžia, ar atsakyti tekstu, ar iškviesti įrankį. Tai numatytoji reikšmė. | Visi modeliai |
"required" | Atsakyme kviečiamas bent vienas įrankis. | Talpinami atvirų svorių modeliai |
{"type": "function", "function": {"name": "get_weather"}} | Atsakyme kviečiama ši funkcija. Pavadinimas turi būti viena iš tools funkcijų. Kreipiniai į kitas funkcijas iš atsakymo pašalinami. | Talpinami atvirų svorių modeliai |
Shannon modeliai (shannon-*) sprendžia kiekvienoje užklausoje, kaip ir su auto.
Naudodami required arba įvardytą funkciją, prieš skaitydami tool_calls perskaitykite finish_reason. Kai modelis kreipinio nesukuria, atsakymas yra tekstinis su finish_reason: "stop".
| Reikšmė | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Modelis sprendžia pats | "auto" | "auto" | {"type": "auto"} |
| Iškviesti bent vieną įrankį | "required" | "required" | {"type": "any"} |
| Iškviesti vieną įvardytą funkciją | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Dėl suderinamumo priimami: tool_choice: "none" ir parallel_tool_calls. Jei ėjimui kreipinių nereikia, siųskite užklausą be tools.
Įrankių kreipiniai atsakyme
| Laukas | Tipas | Aprašymas |
|---|---|---|
finish_reason | string | tool_calls, kai atsakyme yra bent vienas kreipinys. |
message.tool_calls | array | Vienas įrašas kiekvienam kreipiniui. Laukas yra tik tada, kai modelis paprašė kreipinio. |
tool_calls[].id | string | call_ ir 32 šešioliktainiai simboliai. Siųsdami rezultatą, grąžinkite jį kaip tool_call_id. |
tool_calls[].type | string | Visada function. |
tool_calls[].function.name | string | Vykdytina funkcija. |
tool_calls[].function.arguments | string | Argumentai kaip JSON eilutė, "{}", jei jų nėra. Prieš naudodami ją išanalizuokite. |
message.content | string | null | null, kai atsakyme yra tik kreipiniai. Talpinami atvirų svorių modeliai gali grąžinti tekstą šalia kreipinių; Shannon modeliai grąžina null. |
Tas pats kreipinys kiekvienu formatu. Kelyje /v1/responses tai output elementas function_call, kurio arguments yra JSON eilutė. Kelyje /v1/messages tai turinio blokas tool_use, kurio input yra JSON objektas, id prasideda toolu_, o stop_reason yra 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"}
}
]
} Keli kreipiniai viename ėjime
Atsakyme gali būti keli kreipiniai. Vykdykite visus ir kitoje užklausoje siųskite po vieną rezultatą kiekvienam kreipiniui, kiekvieną su savo tool_call_id.
Talpinami atvirų svorių modeliai kiekvieną skirtingą kreipinį grąžina vieną kartą: du kreipiniai su tuo pačiu pavadinimu ir tais pačiais argumentais ateina kaip vienas.
Srautiniai įrankių kreipiniai
Su stream: true kreipinys ateina vienu gabalu: gabale yra visa arguments eilutė, todėl nėra fragmentų, kuriuos reikėtų jungti. index skaičiuoja ėjimo kreipinius nuo 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
}
]
} | Galinis taškas | Kas gaunama |
|---|---|
/v1/chat/completions | Vienas chat.completion.chunk kiekvienam kreipiniui, kreipinys yra delta.tool_calls[0]. Paskutiniame gabale yra finish_reason: "tool_calls" ir usage. |
/v1/responses | Kiekvienam kreipiniui: response.output_item.added (function_call elementas su tuščiu arguments), response.function_call_arguments.delta (visa eilutė), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Kiekvienam kreipiniui: content_block_start (tool_use blokas su tuščiu input), vienas content_block_delta, kurio input_json_delta.partial_json yra visas argumentų tekstas, content_block_stop. Tada message_delta turi stop_reason: "tool_use". |
Su shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ir shannon-coder-1 srautinė užklausa su tools pateikia atsakymo tekstą vienu content delta ėjimo pabaigoje. Srautinė transliacija
Rezultatų grąžinimas
Antroji užklausa pakartoja pokalbį ir prideda du dalykus: asistento ėjimą, kuriame prašyta kreipinių, ir po vieną rezultatą kiekvienam kreipiniui.
{
"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\"}"
}
]
}
]
} - Prieš rezultatus grąžinkite asistento ėjimą tokį, kokį gavote. Kiekvienas rezultatas su kreipiniu susiejamas pagal id:
tool_call_idkelyje/v1/chat/completions,call_idkelyje/v1/responses,tool_use_idkelyje/v1/messages. - Rezultatas yra tekstas. Objektą paverskite JSON eilute ir įrašykite į
content(outputkelyje/v1/responses). Kelyje/v1/messagesblokotool_resultcontentyra eilutė arba tekstinių blokų sąrašas. - Asistento ėjime
function.argumentslieka JSON eilute, lygiai tokia, kokia atėjo. - Pokalbis gali baigtis įrankio rezultatu. Naujo naudotojo pranešimo nereikia: modelis tęsia nuo rezultato.
- Kai jūsų funkcija nepavyksta, klaidą siųskite kaip rezultato tekstą. Tada modelis gali apie ją pranešti arba paprašyti kito kreipinio.
Schemos raktažodžiai
parameters (input_schema kelyje /v1/messages) yra JSON Schema. Shannon 3 šeima (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ir talpinami atvirų svorių modeliai gauna ją tokią, kokią siunčiate.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ir shannon-coder-1 gauna šį poaibį visuose trijuose galiniuose taškuose:
| Apdorojimas | Raktažodžiai |
|---|---|
| Skaitoma taip, kaip išsiųsta | Kiekvienas raktažodis, kuris nepaminėtas toliau esančiose eilutėse, pavyzdžiui, type, properties, required, items, enum, description, minimum, maximum, anyOf ir allOf, visuose schemos lygiuose. |
format | Skaitoma reikšmėms int32, int64, float, double, byte, date, date-time ir enum. |
oneOf | Skaitoma kaip anyOf. |
| Nepatenka į schemą, kurią gauna šie modeliai | $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 ir exclusiveMaximum, kai jie yra skaičiai; kitos format reikšmės. |
Elgsena ir apribojimai
- API nenustato didžiausio įrankių skaičiaus ir didžiausio ratų skaičiaus.
- Užklausos turinys gali siekti 32 MiB, o pokalbis su rezultatais turi tilpti į modelio konteksto langą.
- Kai užklausoje yra
tools,shannon-1.6-lite,shannon-1.6-pro,shannon-2-liteirshannon-2-pronaudoja numatytąjątemperaturereikšmę 0.2. Kitai reikšmei nustatyti siųskitetemperature. - Kiekvienas ratas yra atskira užklausa: ji nuskaičiuojama nuo jūsų balanso ir, kaip ir kitos užklausos, įskaičiuojama į apsaugą nuo užplūdimo. Ribos ir balansas
Klaidos
Įrankio kreipinys yra įprastas atsakymas su būsena 200. Šios klaidos susijusios su pačia užklausa:
| Būsena | Tipas | Pranešimas | Kada |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model nėra paskelbto sąrašo id. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools nėra masyvas arba kitas laukas turi netinkamą JSON tipą. |
413 | invalid_request_error | Failed to buffer the request body: … | Užklausos turinys didesnis nei 32 MiB. Klaidoje yra code: "request_too_large". |
Argumentus rašo modelis. Prieš vykdydami funkciją patikrinkite juos pagal savo schemą, kaip tikrintumėte bet kokius išorinius duomenis.
Autentifikavimo, balanso ir serverio klaidos tokios pačios kaip ir kiekvienai užklausai. Klaidų tvarkymas