કન્ટેન્ટ પર જાઓ
ફંક્શન કોલિંગ

ફંક્શન કોલિંગ

રિક્વેસ્ટમાં તમારા ફંક્શન્સ વર્ણવો અને મોડેલ જે કોલ કરાવવા માંગે તે સાથે જવાબ આપે છે. તમારો કોડ તે ચલાવે છે અને પરિણામો પાછા મોકલે છે: 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 ને parse કરો અને તમારું ફંક્શન ચલાવો.
4 તમે assistant મેસેજ અને દરેક કોલ દીઠ એક 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 આર્ગ્યુમેન્ટ્સ ટોચ પર type: "object" સાથેની JSON Schema તરીકે. નીચે Schema કીવર્ડ્સ જુઓ.

દરેક એન્ડપોઇન્ટનો ટૂલ લખવાનો પોતાનો રીત છે. તમે જે એન્ડપોઇન્ટ કોલ કરો તેને લાગુ પડતો મોકલો:

{
  "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 સ્ટ્રિંગ તરીકે, કોઈ ન હોય ત્યારે "{}". વાપરતાં પહેલાં તેને parse કરો.
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 સાથે, કોલ એક જ ટુકડામાં આવે છે: chunk માં સંપૂર્ણ arguments સ્ટ્રિંગ હોય છે, તેથી જોડવા માટે કોઈ ટુકડા નથી. index ટર્નના કોલ્સ 0 થી ગણે છે.

data: એક chunk, ફોર્મેટ કરેલો
{
  "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] માં. છેલ્લા chunk માં 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 delta માં આપે છે. સ્ટ્રીમિંગ

પરિણામો પાછા મોકલવા

બીજી રિક્વેસ્ટ વાતચીતને પુનરાવર્તિત કરે છે અને બે બાબતો ઉમેરે છે: કોલ માંગનાર 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 (/v1/responses પર output) માટે JSON સ્ટ્રિંગમાં serialise કરો. /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) અને હોસ્ટેડ 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, 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 0.2 નું ડિફોલ્ટ temperature વાપરે છે. બીજી કિંમત સેટ કરવા 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 સામે તપાસો, જેમ તમે કોઈપણ બહારનું ઇનપુટ તપાસો.

પ્રમાણીકરણ, બેલેન્સ અને સર્વર એરર્સ દરેક રિક્વેસ્ટ જેવી જ છે. ભૂલ સંભાળ