फ़ंक्शन कॉलिंग
अनुरोध में अपने फ़ंक्शन बताएँ और मॉडल उन कॉल के साथ उत्तर देता है जो वह चाहता है। आपका कोड उन्हें चलाता है और परिणाम वापस भेजता है: 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 | आप | 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" | उत्तर कम से कम एक टूल कॉल करता है। | होस्टेड ओपन-वेट मॉडल |
{"type": "function", "function": {"name": "get_weather"}} | उत्तर इसी फ़ंक्शन को कॉल करता है। नाम tools में दिए फ़ंक्शन में से एक होना चाहिए। दूसरे फ़ंक्शन की कॉल उत्तर से बाहर रखी जाती हैं। | होस्टेड ओपन-वेट मॉडल |
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। होस्टेड ओपन-वेट मॉडल कॉल के साथ टेक्स्ट भी लौटा सकते हैं; 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 के साथ।
होस्टेड ओपन-वेट मॉडल हर अलग कॉल को एक बार लौटाते हैं: एक ही नाम और एक ही आर्गुमेंट वाली दो कॉल एक के रूप में आती हैं।
स्ट्रीम की गई टूल कॉल
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
}
]
} | Endpoint | क्या आता है |
|---|---|
/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 डेल्टा में देता है। स्ट्रीमिंग
परिणाम वापस भेजना
दूसरा अनुरोध बातचीत दोहराता है और दो चीज़ें जोड़ता है: वह 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 से अपनी कॉल से मिलाया जाता है:
/v1/chat/completionsपरtool_call_id,/v1/responsesपरcall_id,/v1/messagesपरtool_use_id। - परिणाम टेक्स्ट होता है। ऑब्जेक्ट को
contentके लिए JSON स्ट्रिंग में सीरियलाइज़ करें (/v1/responsesपरoutput)।/v1/messagesपरtool_resultब्लॉक काcontentएक स्ट्रिंग या टेक्स्ट ब्लॉक्स की सूची होता है। - assistant टर्न में
function.argumentsJSON स्ट्रिंग ही रहता है, ठीक वैसा ही जैसा आया था। - बातचीत टूल परिणाम पर समाप्त हो सकती है। नए user संदेश की ज़रूरत नहीं: मॉडल परिणाम से आगे बढ़ता है।
- जब आपका फ़ंक्शन विफल हो, तो विफलता को परिणाम टेक्स्ट के रूप में भेजें। तब मॉडल उसकी रिपोर्ट कर सकता है या कोई और कॉल माँग सकता है।
Schema कीवर्ड
parameters (/v1/messages पर input_schema) एक JSON Schema है। Shannon 3 परिवार (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) और होस्टेड ओपन-वेट मॉडल इसे वैसे ही पाते हैं जैसा आप भेजते हैं।
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro और shannon-coder-1 तीनों endpoints पर यह उपसमुच्चय पाते हैं:
| व्यवहार | कीवर्ड |
|---|---|
| जैसा भेजा वैसा पढ़ा जाता है | नीचे की पंक्तियों में न बताया गया हर कीवर्ड, उदाहरण के लिए 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का डिफ़ॉल्टtemperature0.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: … | अनुरोध बॉडी 32 MiB से बड़ी है। त्रुटि में code: "request_too_large" होता है। |
आर्गुमेंट मॉडल लिखता है। फ़ंक्शन चलाने से पहले उन्हें अपने schema से जाँचें, जैसे आप किसी बाहरी इनपुट को जाँचते हैं।
प्रमाणीकरण, बैलेंस और सर्वर की त्रुटियाँ हर अनुरोध जैसी ही हैं। त्रुटि प्रबंधन