फंक्शन कॉलिंग
रिक्वेस्टमध्ये तुमची फंक्शन्स वर्णन करा, आणि मॉडेल हवे असलेले कॉल्स उत्तरात देते. तुमचा कोड ते चालवतो आणि निकाल परत पाठवतो: 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 | तुम्ही | प्रत्येक कॉलचे arguments पार्स करा आणि तुमचे फंक्शन चालवा. |
| 4 | तुम्ही | असिस्टंट संदेश आणि प्रत्येक कॉलसाठी एक tool संदेश messages मध्ये जोडा, मग तेच 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" सह. खाली स्कीमा कीवर्ड्स पाहा. |
प्रत्येक एंडपॉइंटची टूल लिहिण्याची स्वतःची पद्धत आहे. तुम्ही कॉल करत असलेल्या एंडपॉइंटची पद्धत पाठवा:
{
"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" | उत्तर किमान एक टूल कॉल करते. | होस्ट केलेली open-weight मॉडेल्स |
{"type": "function", "function": {"name": "get_weather"}} | उत्तर हे फंक्शन कॉल करते. नाव tools मधील फंक्शन्सपैकी एक असले पाहिजे. इतर फंक्शन्सचे कॉल्स उत्तरातून वगळले जातात. | होस्ट केलेली 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 स्ट्रिंग म्हणून, काहीच नसल्यास "{}". वापरण्यापूर्वी ती पार्स करा. |
message.content | string | null | उत्तरात फक्त कॉल्स असतील तेव्हा null. होस्ट केलेली 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 सह.
होस्ट केलेली open-weight मॉडेल्स प्रत्येक वेगळा कॉल एकदाच परत करतात: सारखे नाव आणि सारखी आर्ग्युमेंट्स असलेले दोन कॉल्स एक म्हणून येतात.
स्ट्रीम केलेले टूल कॉल्स
stream: true सह कॉल एकाच तुकड्यात येतो: चंकमध्ये संपूर्ण 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
}
]
} | एंडपॉइंट | काय येते |
|---|---|
/v1/chat/completions | प्रत्येक कॉलसाठी एक chat.completion.chunk, कॉल delta.tool_calls[0] मध्ये. शेवटच्या चंकमध्ये finish_reason: "tool_calls" आणि usage असतात. |
/v1/responses | प्रत्येक कॉलसाठी: response.output_item.added (रिकामे arguments असलेला function_call आयटम), response.function_call_arguments.delta (संपूर्ण स्ट्रिंग), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | प्रत्येक कॉलसाठी: content_block_start (रिकामा input असलेला tool_use ब्लॉक), एक 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 डेल्टामध्ये देते. स्ट्रीमिंग
निकाल परत पाठवणे
दुसरी रिक्वेस्ट संभाषण पुन्हा देते आणि दोन गोष्टी जोडते: कॉल्स मागणारा असिस्टंट टर्न आणि प्रत्येक कॉलसाठी एक निकाल.
{
"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\"}"
}
]
}
]
} - असिस्टंट टर्न तुम्हाला जसा मिळाला तसाच, निकालांपूर्वी परत पाठवा. प्रत्येक निकाल id द्वारे त्याच्या कॉलशी जुळतो:
/v1/chat/completionsवरtool_call_id,/v1/responsesवरcall_id,/v1/messagesवरtool_use_id. - निकाल म्हणजे मजकूर. ऑब्जेक्ट JSON स्ट्रिंगमध्ये सिरियलाईज करून
contentमध्ये द्या (/v1/responsesवरoutput)./v1/messagesवरtool_resultब्लॉकचाcontentस्ट्रिंग किंवा टेक्स्ट ब्लॉक्सची यादी असतो. - असिस्टंट टर्नमध्ये
function.argumentsजसे आले तसेच JSON स्ट्रिंग राहते. - संभाषण टूल निकालाने संपू शकते. नवीन युजर संदेशाची गरज नाही: मॉडेल निकालापासून पुढे चालू ठेवते.
- तुमचे फंक्शन अयशस्वी झाले तर अपयश निकालाचा मजकूर म्हणून पाठवा. मग मॉडेल ते कळवू शकते किंवा दुसरा कॉल मागू शकते.
स्कीमा कीवर्ड्स
parameters (/v1/messages वर input_schema) हा JSON Schema आहे. Shannon 3 कुटुंब (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) आणि होस्ट केलेली open-weight मॉडेल्स तो तुम्ही पाठवता तसाच घेतात.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro आणि shannon-coder-1 तिन्ही एंडपॉइंट्सवर हा उपसंच घेतात:
| हाताळणी | कीवर्ड्स |
|---|---|
| पाठवल्याप्रमाणे वाचले जाते | खालील ओळींमध्ये नाव न दिलेला प्रत्येक कीवर्ड, उदाहरणार्थ 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 टूल्सची कमाल संख्या किंवा फेऱ्यांची कमाल संख्या ठरवत नाही.
- रिक्वेस्ट बॉडी 32 MiB पर्यंत असू शकते, आणि निकालांसह संभाषण मॉडेलच्या कॉन्टेक्स्ट विंडोमध्ये बसले पाहिजे.
- रिक्वेस्टमध्ये
toolsअसतील तेव्हाshannon-1.6-lite,shannon-1.6-pro,shannon-2-liteआणिshannon-2-proडिफॉल्टtemperature0.2 वापरतात. दुसरे मूल्य हवे असल्यासtemperatureपाठवा. - प्रत्येक फेरी स्वतंत्र रिक्वेस्ट आहे: ती तुमच्या बॅलन्समधून वापरते आणि इतर रिक्वेस्टप्रमाणे फ्लड प्रोटेक्शनमध्ये मोजली जाते. मर्यादा आणि बॅलन्स
त्रुटी
टूल कॉल हे स्टेटस 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" असते. |
आर्ग्युमेंट्स मॉडेल लिहिते. फंक्शन चालवण्यापूर्वी, कोणत्याही बाहेरच्या इनपुटप्रमाणे, ती तुमच्या स्कीमाविरुद्ध तपासा.
प्रमाणीकरण, बॅलन्स आणि सर्व्हर त्रुटी प्रत्येक रिक्वेस्टप्रमाणेच आहेत. त्रुटी हाताळणी