मजकुराकडे जा
फंक्शन कॉलिंग

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

रिक्वेस्टमध्ये तुमची फंक्शन्स वर्णन करा, आणि मॉडेल हवे असलेले कॉल्स उत्तरात देते. तुमचा कोड ते चालवतो आणि निकाल परत पाठवतो: 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 तुम्ही असिस्टंट संदेश आणि प्रत्येक कॉलसाठी एक 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"]
    }
  }
}

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

एका टर्नमध्ये अनेक कॉल्स

एका उत्तरात अनेक कॉल्स असू शकतात. ते सर्व चालवा आणि पुढच्या रिक्वेस्टमध्ये प्रत्येक कॉलसाठी एक निकाल पाठवा, प्रत्येकाच्या स्वतःच्या tool_call_id सह.

होस्ट केलेली open-weight मॉडेल्स प्रत्येक वेगळा कॉल एकदाच परत करतात: सारखे नाव आणि सारखी आर्ग्युमेंट्स असलेले दोन कॉल्स एक म्हणून येतात.

स्ट्रीम केलेले टूल कॉल्स

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
    }
  ]
}
एंडपॉइंट काय येते
/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\"}"
    }
  ]
}
  • असिस्टंट टर्न तुम्हाला जसा मिळाला तसाच, निकालांपूर्वी परत पाठवा. प्रत्येक निकाल 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 डिफॉल्ट temperature 0.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" असते.

आर्ग्युमेंट्स मॉडेल लिहिते. फंक्शन चालवण्यापूर्वी, कोणत्याही बाहेरच्या इनपुटप्रमाणे, ती तुमच्या स्कीमाविरुद्ध तपासा.

प्रमाणीकरण, बॅलन्स आणि सर्व्हर त्रुटी प्रत्येक रिक्वेस्टप्रमाणेच आहेत. त्रुटी हाताळणी