Ֆունկցիայի կանչ
Նկարագրեք ձեր ֆունկցիաները հարցման մեջ, և մոդելը պատասխանում է այն կանչերով, որոնք ցանկանում է կատարել։ Ձեր կոդը կատարում է դրանք և արդյունքները ուղարկում հետ. API-ն վերադարձնում է գործիքների կանչեր և ինքը գործիք չի կատարում։
POST https://api.shannon-ai.com/v1/chat/completions
Այս էջի օրինակներն օգտագործում են /v1/chat/completions։ Նույն ցիկլն աշխատում է /v1/responses-ում և /v1/messages-ում. որտեղ ձևաչափերը ինչ-որ բան այլ կերպ են գրում, ստորև բաժինները ցույց են տալիս երեքն էլ։
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"]
}
}
}]
}' Առաջին պատասխանը հարցին չի պատասխանում։ Այն կանչ է խնդրում.
{
"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}
}
} Արդյունքը ուղարկելուց հետո հաջորդ պատասխանը սովորական պատասխան է. message.content-ը պարունակում է տեքստը, և finish_reason-ը stop է։
Ցիկլը՝ քայլ առ քայլ
| Քայլ | Ով | Ինչ է տեղի ունենում |
|---|---|---|
| 1 | Դուք | Ուղարկեք messages՝ tools-ի հետ, այն ֆունկցիաների ցանկը, որոնք մոդելը կարող է խնդրել։ |
| 2 | Մոդել | Պատասխանը կրում է tool_calls և finish_reason: "tool_calls"։ Յուրաքանչյուր կանչ նշում է ֆունկցիան և տալիս նրա արգումենտները։ |
| 3 | Դուք | Վերլուծեք (parse) յուրաքանչյուր կանչի arguments-ը և կատարեք ձեր ֆունկցիան։ |
| 4 | Դուք | messages-ին կցեք assistant հաղորդագրությունը և մեկական tool հաղորդագրություն յուրաքանչյուր կանչի համար, ապա նույն tools-ով կրկին ուղարկեք հարցումը։ |
| 5 | Մոդել | Մոդելը պատասխանում է տեքստով՝ finish_reason: "stop"-ով, կամ խնդրում է նոր կանչեր։ Այդ դեպքում վերադարձեք 3-րդ քայլին։ |
Մեկ հարցումը մոդելի մեկ փուլ է։ API-ն հարցումների միջև զրույց չի պահում և փուլերի քանակ չի սահմանում. messages-ը պահում է ձեր կոդը և որոշում, թե երբ կանգ առնել։
Գործիքների սահմանում
tools-ը զանգված է՝ մեկ գրառմամբ յուրաքանչյուր ֆունկցիայի համար։ Կատալոգի յուրաքանչյուր մոդել ընդունում է այն. GET /v1/models-ը յուրաքանչյուր id-ի համար ցույց է տալիս capabilities.tools: true։
| Դաշտ | Տեսակ | Նկարագրություն |
|---|---|---|
type | string | Միշտ function։ |
function.name | string | Անունը, որը մոդելն օգտագործում է այս ֆունկցիան խնդրելիս։ Պարտադիր է։ |
function.description | string | Ինչ է անում ֆունկցիան՝ պարզ լեզվով։ |
function.parameters | object | Արգումենտները որպես JSON Schema՝ վերևում type: "object"-ով։ Տես ստորև Schema-ի բանալի բառեր։ |
Յուրաքանչյուր endpoint ունի գործիքի իր գրելաձևը։ Ուղարկեք այն, որը պատկանում է ձեր կանչած endpoint-ին.
{
"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-ը ասում է՝ մոդելը կարող է, թե պարտավոր է գործիք կանչել։ Այն կարդացվում է միայն tools-ի հետ միասին։
| Արժեք | Նկարագրություն | Կիրառվում է |
|---|---|---|
"auto" | Մոդելն ինքն է որոշում՝ պատասխանել տեքստով, թե կանչել գործիք։ Սա լռելյայն արժեքն է։ | Բոլոր մոդելները |
"required" | Պատասխանը կանչում է առնվազն մեկ գործիք։ | Hosted open-weight մոդելներ |
{"type": "function", "function": {"name": "get_weather"}} | Պատասխանը կանչում է այս ֆունկցիան։ Անունը պետք է լինի tools-ում եղած ֆունկցիաներից մեկը։ Այլ ֆունկցիաների կանչերը պատասխանից դուրս են թողնվում։ | Hosted open-weight մոդելներ |
Shannon մոդելները (shannon-*) որոշում են յուրաքանչյուր հարցման մեջ, ինչպես auto-ի դեպքում։
required-ի կամ անվանված ֆունկցիայի դեպքում tool_calls-ը կարդալուց առաջ կարդացեք finish_reason-ը։ Երբ մոդելը կանչ չի ստեղծում, պատասխանը տեքստային է՝ finish_reason: "stop"-ով։
| Նշանակություն | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Մոդելն ինքն է որոշում | "auto" | "auto" | {"type": "auto"} |
| Կանչել առնվազն մեկ գործիք | "required" | "required" | {"type": "any"} |
| Կանչել մեկ անվանված ֆունկցիա | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Ընդունվում են համատեղելիության համար՝ tool_choice: "none" և parallel_tool_calls։ Գործիքի կանչեր չունեցող փուլի համար ուղարկեք հարցումն առանց tools-ի։
Գործիքի կանչերը պատասխանում
| Դաշտ | Տեսակ | Նկարագրություն |
|---|---|---|
finish_reason | string | tool_calls, երբ պատասխանը կրում է առնվազն մեկ կանչ։ |
message.tool_calls | array | Մեկ գրառում յուրաքանչյուր կանչի համար։ Դաշտը առկա է միայն այն դեպքում, երբ մոդելը կանչ է խնդրել։ |
tool_calls[].id | string | call_, որին հաջորդում են 32 տասնվեցական նիշ։ Արդյունքի հետ ուղարկեք այն հետ որպես tool_call_id։ |
tool_calls[].type | string | Միշտ function։ |
tool_calls[].function.name | string | Կատարվելիք ֆունկցիան։ |
tool_calls[].function.arguments | string | Արգումենտները որպես JSON տող, "{}", երբ դրանք չկան։ Օգտագործելուց առաջ վերլուծեք (parse) այն։ |
message.content | string | null | null, երբ պատասխանը պարունակում է միայն կանչեր։ Hosted open-weight մոդելները կարող են տեքստ վերադարձնել կանչերի կողքին. Shannon մոդելները վերադարձնում են null։ |
Նույն կանչը յուրաքանչյուր ձևաչափում։ /v1/responses-ում դա output-ի function_call տարր է, որի arguments-ը JSON տող է։ /v1/messages-ում դա tool_use բովանդակության բլոկ է, որի input-ը JSON օբյեկտ է, id-ն սկսվում է toolu_-ով, իսկ stop_reason-ը 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"}
}
]
} Մի քանի կանչ մեկ փուլում
Պատասխանը կարող է կրել մի քանի կանչ։ Կատարեք յուրաքանչյուրը և հաջորդ հարցմանը ուղարկեք մեկական արդյունք յուրաքանչյուր կանչի համար՝ իր tool_call_id-ով։
Hosted open-weight մոդելները յուրաքանչյուր տարբեր կանչը վերադարձնում են մեկ անգամ. նույն անունով և նույն արգումենտներով երկու կանչ գալիս է որպես մեկ։
Streaming գործիքի կանչեր
stream: true-ով կանչը գալիս է մեկ կտորով. chunk-ը պարունակում է arguments ամբողջական տողը, ուստի միացնելու հատվածներ չկան։ index-ը փուլի կանչերը համարակալում է 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 | Ինչ է գալիս |
|---|---|
/v1/chat/completions | Մեկ chat.completion.chunk յուրաքանչյուր կանչի համար, կանչը՝ delta.tool_calls[0]-ում։ Վերջին chunk-ն ունի finish_reason: "tool_calls" և usage։ |
/v1/responses | Յուրաքանչյուր կանչի համար՝ response.output_item.added (function_call տարր դատարկ arguments-ով), response.function_call_arguments.delta (ամբողջ տողը), response.function_call_arguments.done, response.output_item.done։ |
/v1/messages | Յուրաքանչյուր կանչի համար՝ content_block_start (tool_use բլոկ դատարկ input-ով), մեկ content_block_delta, որի input_json_delta.partial_json-ը արգումենտների ամբողջ տեքստն է, content_block_stop։ Ապա message_delta-ն կրում է stop_reason: "tool_use"։ |
shannon-1.6-lite-ի, shannon-1.6-pro-ի, shannon-2-lite-ի, shannon-2-pro-ի և shannon-coder-1-ի վրա tools կրող streaming հարցումը իր պատասխանի տեքստը տալիս է մեկ content delta-ով՝ փուլի վերջում։ Ստրիմինգ
Արդյունքների ուղարկումը հետ
Երկրորդ հարցումը կրկնում է զրույցը և ավելացնում երկու բան՝ assistant փուլը, որը կանչեր էր խնդրել, և մեկ արդյունք յուրաքանչյուր կանչի համար։
{
"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\"}"
}
]
}
]
} - Assistant փուլը արդյունքներից առաջ ուղարկեք հետ այնպես, ինչպես ստացել եք։ Յուրաքանչյուր արդյունք իր կանչին կապվում է id-ով՝
tool_call_id/v1/chat/completions-ում,call_id/v1/responses-ում,tool_use_id/v1/messages-ում։ - Արդյունքը տեքստ է։ Օբյեկտը սերիալիզացրեք JSON տողի
content-ի համար (output/v1/responses-ում)։/v1/messages-ումtool_resultբլոկիcontent-ը տող է կամ տեքստային բլոկների ցանկ։ - Assistant փուլում
function.arguments-ը մնում է JSON տող՝ ճիշտ այնպես, ինչպես եկել է։ - Զրույցը կարող է ավարտվել գործիքի արդյունքով։ Նոր օգտատիրոջ հաղորդագրություն պետք չէ. մոդելը շարունակում է արդյունքից։
- Երբ ձեր ֆունկցիան ձախողվում է, ձախողումն ուղարկեք որպես արդյունքի տեքստ։ Այդ դեպքում մոդելը կարող է հայտնել դրա մասին կամ խնդրել այլ կանչ։
Schema-ի բանալի բառեր
parameters-ը (input_schema /v1/messages-ում) JSON Schema է։ Shannon 3 ընտանիքը (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) և hosted open-weight մոդելները ստանում են այն այնպես, ինչպես ուղարկում եք։
shannon-1.6-lite-ը, shannon-1.6-pro-ն, shannon-2-lite-ը, shannon-2-pro-ն և shannon-coder-1-ը ստանում են այս ենթաբազմությունը՝ երեք endpoint-ներում էլ.
| Վերաբերմունք | Բանալի բառեր |
|---|---|
| Կարդացվում է այնպես, ինչպես ուղարկվել է | Յուրաքանչյուր բանալի բառ, որը չի նշված ստորև տողերում, օրինակ՝ type, properties, required, items, enum, description, minimum, maximum, anyOf և allOf, schema-ի յուրաքանչյուր մակարդակում։ |
format | Կարդացվում է int32, int64, float, double, byte, date, date-time և enum արժեքների համար։ |
oneOf | Կարդացվում է որպես anyOf։ |
| Այս մոդելների ստացած schema-ի մաս չէ | $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 և exclusiveMaximum, երբ դրանք թվեր են. format-ի մյուս արժեքները։ |
Վարքագիծ և սահմանաչափեր
- API-ն գործիքների առավելագույն քանակ և փուլերի առավելագույն քանակ չի սահմանում։
- Հարցման մարմինը կարող է լինել մինչև 32 MiB, և զրույցը՝ արդյունքներով հանդերձ, պետք է տեղավորվի մոդելի համատեքստի պատուհանում։
- Երբ հարցումը կրում է
tools,shannon-1.6-lite-ը,shannon-1.6-pro-ն,shannon-2-lite-ը ևshannon-2-pro-ն օգտագործում ենtemperature-ի լռելյայն 0.2 արժեքը։ Այլ արժեք սահմանելու համար ուղարկեքtemperature։ - Յուրաքանչյուր փուլ առանձին հարցում է. այն ծախսում է ձեր մնացորդից և հաշվվում է flood-պաշտպանության մեջ, ինչպես ցանկացած այլ հարցում։ Սահմանաչափեր և մնացորդ
Սխալներ
Գործիքի կանչը սովորական պատասխան է 200 կարգավիճակով։ Այս սխալները վերաբերում են հենց հարցմանը.
| Կարգավիճակ | Տեսակ | Հաղորդագրություն | Երբ |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model-ը հրապարակված ցանկի id չէ։ |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools-ը զանգված չէ, կամ մեկ այլ դաշտ ունի սխալ JSON տեսակ։ |
413 | invalid_request_error | Failed to buffer the request body: … | Հարցման մարմինը մեծ է 32 MiB-ից։ Սխալը կրում է code: "request_too_large"։ |
Արգումենտները գրում է մոդելը։ Ստուգեք դրանք ձեր schema-ով՝ ֆունկցիան կատարելուց առաջ, ինչպես ստուգում եք ցանկացած արտաքին մուտք։
Վավերացման, մնացորդի և սերվերի սխալները նույնն են, ինչ յուրաքանչյուր հարցման համար։ Սխալների մշակում