Funksiya chaqirish
Funksiyalaringizni so'rovda tasvirlang va model bajarilishini istagan chaqiruvlar bilan javob beradi. Kodingiz ularni bajaradi va natijalarni qaytaradi: API tool chaqiruvlarini qaytaradi va tool'ni o'zi bajarmaydi.
POST https://api.shannon-ai.com/v1/chat/completions
Bu sahifadagi namunalar /v1/chat/completionsdan foydalanadi. Xuddi shu sikl /v1/responses va /v1/messages da ham ishlaydi; format biror narsani boshqacha yozsa, quyidagi bo'limlarda uchalasi ham ko'rsatilgan.
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"]
}
}
}]
}' Birinchi javob savolga javob bermaydi. U chaqiruvni so'raydi:
{
"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}
}
} Natijani yuborganingizdan so'ng keyingi javob oddiy javob bo'ladi: message.content matnni o'z ichiga oladi va finish_reason stop.
Sikl, qadamma-qadam
| Qadam | Kim | Nima bo'ladi |
|---|---|---|
| 1 | Siz | messagesni tools bilan birga yuboring, bu model so'rashi mumkin bo'lgan funksiyalar ro'yxati. |
| 2 | Model | Javob tool_calls va finish_reason: "tool_calls"ni olib keladi. Har bir chaqiruv funksiyani nomlaydi va argumentlarini beradi. |
| 3 | Siz | Har bir chaqiruvning argumentsini parse qiling va funksiyangizni bajaring. |
| 4 | Siz | Assistant xabarini va har bir chaqiruv uchun bitta tool xabarini messagesga qo'shing, so'ng so'rovni o'sha tools bilan qayta yuboring. |
| 5 | Model | Model finish_reason: "stop" bilan matnda javob beradi yoki yana chaqiruvlar so'raydi. Bu holda 3-qadamga qayting. |
Bitta so'rov — modelning bitta navbati. API so'rovlar orasida suhbatni saqlamaydi va raundlar sonini belgilamaydi: messagesni kodingiz saqlaydi va qachon to'xtashni hal qiladi.
Tool'larni belgilash
tools — har bir funksiyaga bitta elementli massiv. Katalogdagi har bir model uni qabul qiladi; GET /v1/models har bir id uchun capabilities.tools: trueni ko'rsatadi.
| Maydon | Tur | Tavsif |
|---|---|---|
type | string | Doim function. |
function.name | string | Model bu funksiyani so'raganda ishlatadigan nom. Majburiy. |
function.description | string | Funksiya nima qiladi, oddiy tilda. |
function.parameters | object | Argumentlar yuqorida type: "object" bo'lgan JSON Schema sifatida. Quyida Sxema kalit so'zlariga qarang. |
Har bir endpointning tool yozilishi o'ziniki. Chaqirayotgan endpointingizga tegishlisini yuboring:
{
"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 modelning tool chaqirishi mumkinmi yoki shartmi, shuni aytadi. U faqat tools bilan birga o'qiladi.
| Qiymat | Tavsif | Qo'llaydi |
|---|---|---|
"auto" | Model matn bilan javob berish yoki tool chaqirishni o'zi hal qiladi. Bu standart. | Barcha modellar |
"required" | Javob kamida bitta tool chaqiradi. | Xostingdagi open-weight modellar |
{"type": "function", "function": {"name": "get_weather"}} | Javob shu funksiyani chaqiradi. Nom toolsdagi funksiyalardan biri bo'lishi kerak. Boshqa funksiyalarga chaqiruvlar javobga kiritilmaydi. | Xostingdagi open-weight modellar |
Shannon modellari (shannon-*) har bir so'rovda autodagidek o'zi hal qiladi.
required yoki nomlangan funksiya bilan tool_callsni o'qishdan oldin finish_reasonni o'qing. Model chaqiruv hosil qilmasa, javob finish_reason: "stop" bilan matnli javob bo'ladi.
| Ma'nosi | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Model o'zi hal qiladi | "auto" | "auto" | {"type": "auto"} |
| Kamida bitta tool chaqirish | "required" | "required" | {"type": "any"} |
| Bitta nomlangan funksiyani chaqirish | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Moslik uchun qabul qilinadi: tool_choice: "none" va parallel_tool_calls. Tool chaqiruvlarisiz navbat uchun so'rovni toolssiz yuboring.
Javobdagi tool chaqiruvlari
| Maydon | Tur | Tavsif |
|---|---|---|
finish_reason | string | Javobda kamida bitta chaqiruv bo'lsa tool_calls. |
message.tool_calls | array | Har bir chaqiruvga bitta element. Maydon faqat model chaqiruv so'raganda bo'ladi. |
tool_calls[].id | string | call_ va undan keyin 32 ta o'n oltilik belgi. Natija bilan birga uni tool_call_id sifatida qaytaring. |
tool_calls[].type | string | Doim function. |
tool_calls[].function.name | string | Bajariladigan funksiya. |
tool_calls[].function.arguments | string | Argumentlar JSON satri sifatida, yo'q bo'lsa "{}". Ishlatishdan oldin uni parse qiling. |
message.content | string | null | Javobda faqat chaqiruvlar bo'lsa null. Xostingdagi open-weight modellar chaqiruvlar yonida matn qaytarishi mumkin; Shannon modellari null qaytaradi. |
Xuddi shu chaqiruv har bir formatda. /v1/responses da u outputning function_call elementi, arguments JSON satri sifatida. /v1/messages da u inputi JSON obyekti bo'lgan tool_use kontent bloki, uning idsi toolu_ bilan boshlanadi va 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"}
}
]
} Bir navbatda bir nechta chaqiruv
Javob bir nechta chaqiruvni olib kelishi mumkin. Ularning hammasini bajaring va keyingi so'rovda har biri o'z tool_call_idsi bilan har bir chaqiruv uchun bitta natija yuboring.
Xostingdagi open-weight modellar har bir alohida chaqiruvni bir marta qaytaradi: nomi va argumentlari bir xil ikki chaqiruv bitta bo'lib keladi.
Oqimli tool chaqiruvlari
stream: true bilan chaqiruv bir butun bo'lib keladi: chunk to'liq arguments satrini o'z ichiga oladi, shuning uchun birlashtiriladigan bo'laklar yo'q. index navbat chaqiruvlarini 0 dan sanaydi.
{
"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 | Nima keladi |
|---|---|
/v1/chat/completions | Har bir chaqiruvga bitta chat.completion.chunk, chaqiruv delta.tool_calls[0]da. Oxirgi chunkda finish_reason: "tool_calls" va usage bor. |
/v1/responses | Har bir chaqiruv uchun: response.output_item.added (bo'sh argumentsli function_call elementi), response.function_call_arguments.delta (butun satr), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Har bir chaqiruv uchun: content_block_start (bo'sh inputli tool_use bloki), input_json_delta.partial_jsoni butun argumentlar matni bo'lgan bitta content_block_delta, content_block_stop. Keyin message_delta stop_reason: "tool_use"ni olib keladi. |
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro va shannon-coder-1 da toolsni olib keladigan oqimli so'rov javob matnini navbat oxirida bitta content deltasida yetkazadi. Oqim
Natijalarni qaytarish
Ikkinchi so'rov suhbatni takrorlaydi va ikki narsa qo'shadi: chaqiruvlarni so'ragan assistant navbati va har bir chaqiruv uchun bitta natija.
{
"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 navbatini natijalardan oldin olganingizdek qaytaring. Har bir natija o'z chaqiruviga id bo'yicha moslanadi:
/v1/chat/completionsdatool_call_id,/v1/responsesdacall_id,/v1/messagesdatool_use_id. - Natija — matn. Obyektni
contentuchun (/v1/responsesdaoutput) JSON satriga serializatsiya qiling./v1/messagesdatool_resultblokiningcontenti satr yoki matn bloklari ro'yxati. - Assistant navbatida
function.argumentskelganidek, JSON satri bo'lib qoladi. - Suhbat tool natijasi bilan tugashi mumkin. Yangi foydalanuvchi xabari kerak emas: model natijadan davom etadi.
- Funksiyangiz muvaffaqiyatsiz bo'lsa, nosozlikni natija matni sifatida yuboring. Shunda model uni xabar qilishi yoki boshqa chaqiruv so'rashi mumkin.
Sxema kalit so'zlari
parameters (/v1/messages da input_schema) — JSON Schema. Shannon 3 oilasi (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) va xostingdagi open-weight modellar uni yuborganingizdek oladi.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro va shannon-coder-1 uchala endpointda ham shu qism to'plamni oladi:
| Ishlov | Kalit so'zlar |
|---|---|
| Yuborilganidek o'qiladi | Quyidagi qatorlarda nomlanmagan har bir kalit so'z, masalan type, properties, required, items, enum, description, minimum, maximum, anyOf va allOf, sxemaning har bir darajasida. |
format | int32, int64, float, double, byte, date, date-time va enum qiymatlari uchun o'qiladi. |
oneOf | anyOf sifatida o'qiladi. |
| Bu modellar oladigan sxemaga kirmaydi | $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; son bo'lganda exclusiveMinimum va exclusiveMaximum; formatning boshqa qiymatlari. |
Xatti-harakat va limitlar
- API tool'lar sonining ham, raundlar sonining ham maksimumini belgilamaydi.
- So'rov tanasi 32 MiB gacha bo'lishi mumkin, natijalari bilan suhbat esa modelning kontekst oynasiga sig'ishi kerak.
- So'rov
toolsni olib kelgandashannon-1.6-lite,shannon-1.6-pro,shannon-2-litevashannon-2-prostandarttemperature0.2 dan foydalanadi. Boshqa qiymat uchuntemperatureni yuboring. - Har bir raund o'z so'rovi: u balansingizdan oladi va boshqa so'rov kabi flood himoyasiga hisoblanadi. Limitlar va balans
Xatolar
Tool chaqiruvi 200 holatli oddiy javob. Bu xatolar so'rovning o'ziga tegishli:
| Holat | Tur | Xabar | Qachon |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model e'lon qilingan ro'yxatdagi id emas. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools massiv emas yoki boshqa maydon noto'g'ri JSON turida. |
413 | invalid_request_error | Failed to buffer the request body: … | So'rov tanasi 32 MiB dan katta. Xatoda code: "request_too_large" bor. |
Argumentlarni model yozadi. Funksiyani bajarishdan oldin ularni sxemangizga qarshi tekshiring, har qanday tashqi kirishni tekshirganingizdek.
Autentifikatsiya, balans va server xatolari har bir so'rovdagi bilan bir xil. Xatolarni boshqarish