ფუნქციის გამოძახება
აღწერეთ თქვენი ფუნქციები მოთხოვნაში და მოდელი გიპასუხებთ გამოძახებებით, რომელთა შესრულებაც სურს. თქვენი კოდი მათ ასრულებს და შედეგებს უკან აგზავნის: 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"-ით. იხილეთ ქვემოთ სქემის საკვანძო სიტყვები. |
თითოეულ 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-ზე ის არის function_call ელემენტი output-ში, 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 მოდელები თითოეულ განსხვავებულ გამოძახებას ერთხელ აბრუნებენ: ორი გამოძახება ერთი და იმავე სახელითა და ერთი და იმავე არგუმენტებით ერთად მოდის.
სტრიმული ინსტრუმენტების გამოძახებები
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-ს ატარებს, პასუხის ტექსტს ერთ 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 სტრიქონად, ზუსტად ისე, როგორც მოვიდა. - საუბარი შეიძლება ინსტრუმენტის შედეგით დასრულდეს. ახალი user შეტყობინება საჭირო არ არის: მოდელი შედეგიდან აგრძელებს.
- როცა თქვენი ფუნქცია ვერ სრულდება, წარუმატებლობა შედეგის ტექსტად გააგზავნეთ. მოდელს შემდეგ შეუძლია ამის შესახებ აცნობოს ან სხვა გამოძახება მოითხოვოს.
სქემის საკვანძო სიტყვები
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, სქემის ყველა დონეზე. |
format | იკითხება მნიშვნელობებისთვის int32, int64, float, double, byte, date, date-time და enum. |
oneOf | იკითხება როგორც anyOf. |
| არ შედის სქემაში, რომელსაც ეს მოდელები იღებენ | $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 არ ადგენს ინსტრუმენტების მაქსიმალურ რაოდენობას და ტურების მაქსიმალურ რაოდენობას.
- მოთხოვნის body შეიძლება 32 MiB-მდე იყოს და საუბარი თავისი შედეგებით მოდელის კონტექსტის ფანჯარაში უნდა ეტეოდეს.
- როცა მოთხოვნა ატარებს
tools-ს,shannon-1.6-lite,shannon-1.6-pro,shannon-2-liteდაshannon-2-proნაგულისხმევtemperature-ს 0.2-ს იყენებენ. სხვა მნიშვნელობის დასაყენებლად გააგზავნეთtemperature. - ყოველი ტური ცალკე მოთხოვნაა: ის თქვენს ბალანსს ხარჯავს და flood protection-ში ნებისმიერი სხვა მოთხოვნასავით ითვლება. ლიმიტები და ბალანსი
შეცდომები
ინსტრუმენტის გამოძახება ჩვეულებრივი პასუხია სტატუსით 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: … | მოთხოვნის body 32 MiB-ზე დიდია. შეცდომა ატარებს code: "request_too_large"-ს. |
არგუმენტებს მოდელი წერს. ფუნქციის შესრულებამდე შეამოწმეთ ისინი თქვენი სქემის მიხედვით, ისევე როგორც ნებისმიერ გარე შეტანას.
ავთენტიკაციის, ბალანსისა და სერვერის შეცდომები იგივეა, რაც ნებისმიერი მოთხოვნისთვის. შეცდომების დამუშავება