कंटेंट पर जाएँ
फ़ंक्शन कॉलिंग

फ़ंक्शन कॉलिंग

अनुरोध में अपने फ़ंक्शन बताएँ और मॉडल उन कॉल के साथ उत्तर देता है जो वह चाहता है। आपका कोड उन्हें चलाता है और परिणाम वापस भेजता है: 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)

पहला उत्तर प्रश्न का जवाब नहीं देता। वह एक कॉल माँगता है:

200 JSON
{
  "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"]
    }
  }
}

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\"}"
        }
      }
    ]
  }
}

एक टर्न में कई कॉल

एक उत्तर में कई कॉल हो सकती हैं। उन सभी को चलाएँ और अगले अनुरोध में हर कॉल का एक परिणाम भेजें, हर एक अपने tool_call_id के साथ।

होस्टेड ओपन-वेट मॉडल हर अलग कॉल को एक बार लौटाते हैं: एक ही नाम और एक ही आर्गुमेंट वाली दो कॉल एक के रूप में आती हैं।

स्ट्रीम की गई टूल कॉल

stream: true के साथ कॉल एक ही टुकड़े में आती है: चंक में पूरी arguments स्ट्रिंग होती है, इसलिए जोड़ने के लिए कोई टुकड़े नहीं हैं। index टर्न की कॉल को 0 से गिनता है।

data: एक चंक, फ़ॉर्मेट किया हुआ
{
  "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\"}"
    }
  ]
}
  • 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.arguments JSON स्ट्रिंग ही रहता है, ठीक वैसा ही जैसा आया था।
  • बातचीत टूल परिणाम पर समाप्त हो सकती है। नए 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 का डिफ़ॉल्ट 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: … अनुरोध बॉडी 32 MiB से बड़ी है। त्रुटि में code: "request_too_large" होता है।

आर्गुमेंट मॉडल लिखता है। फ़ंक्शन चलाने से पहले उन्हें अपने schema से जाँचें, जैसे आप किसी बाहरी इनपुट को जाँचते हैं।

प्रमाणीकरण, बैलेंस और सर्वर की त्रुटियाँ हर अनुरोध जैसी ही हैं। त्रुटि प्रबंधन