உள்ளடக்கத்துக்குச் செல்
செயல்பாடு அழைப்பு

செயல்பாடு அழைப்பு

கோரிக்கையில் உங்கள் செயல்பாடுகளை விவரியுங்கள்; மாடல் தான் செய்யச் சொல்லும் அழைப்புகளுடன் பதிலளிக்கும். உங்கள் குறியீடு அவற்றை இயக்கி முடிவுகளைத் திருப்பி அனுப்பும்: API tool அழைப்புகளைத் தருகிறது, tool-ஐத் தானே இயக்குவதில்லை.

POST https://api.shannon-ai.com/v1/chat/completions

இந்தப் பக்கத்தின் மாதிரிகள் /v1/chat/completions-ஐப் பயன்படுத்துகின்றன. அதே loop /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.

loop, படிப்படியாக

படி யார் என்ன நடக்கும்
1 நீங்கள் messages-ஐ, மாடல் கேட்கக்கூடிய செயல்பாடுகளின் பட்டியலான tools-உடன் சேர்த்து அனுப்புங்கள்.
2 மாடல் பதிலில் tool_calls மற்றும் finish_reason: "tool_calls" இருக்கும். ஒவ்வொரு அழைப்பும் ஒரு செயல்பாட்டின் பெயரையும் அதன் arguments-ஐயும் தரும்.
3 நீங்கள் ஒவ்வொரு அழைப்பின் arguments-ஐ parse செய்து உங்கள் செயல்பாட்டை இயக்குங்கள்.
4 நீங்கள் assistant செய்தியையும் ஒவ்வொரு அழைப்புக்கும் ஒரு tool செய்தியையும் messages-ல் சேர்த்து, அதே tools-உடன் கோரிக்கையை மீண்டும் அனுப்புங்கள்.
5 மாடல் மாடல் finish_reason: "stop" உடன் உரையில் பதிலளிக்கும், அல்லது மேலும் அழைப்புகளைக் கேட்கும். அந்த நிலையில் படி 3-க்குத் திரும்புங்கள்.

ஒரு கோரிக்கை என்பது மாடலின் ஒரு சுற்று. கோரிக்கைகளுக்கு இடையே API உரையாடலை வைத்திருப்பதில்லை, சுற்றுகளின் எண்ணிக்கையையும் நிர்ணயிப்பதில்லை: messages-ஐ உங்கள் குறியீடு வைத்திருந்து, எப்போது நிறுத்துவது என்பதை முடிவு செய்கிறது.

Tools-ஐ வரையறுத்தல்

tools என்பது ஒரு செயல்பாட்டுக்கு ஒரு உள்ளீடு கொண்ட array. பட்டியலிலுள்ள ஒவ்வொரு மாடலும் இதை ஏற்கிறது; GET /v1/models ஒவ்வொரு id-க்கும் capabilities.tools: true எனத் தெரிவிக்கிறது.

புலம் வகை விளக்கம்
type string எப்போதும் function.
function.name string இந்தச் செயல்பாட்டைக் கேட்கும்போது மாடல் பயன்படுத்தும் பெயர். கட்டாயம்.
function.description string செயல்பாடு என்ன செய்கிறது, எளிய மொழியில்.
function.parameters object மேலே type: "object" கொண்ட JSON Schema ஆக arguments. கீழே உள்ள Schema keywords பகுதியைப் பாருங்கள்.

ஒவ்வொரு endpoint-க்கும் tool-ஐ எழுதும் தனி வடிவம் உண்டு. நீங்கள் அழைக்கும் 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-ஐ அழைக்கலாமா, அல்லது அழைத்தே ஆக வேண்டுமா என்பதை tool_choice கூறுகிறது. இது tools-உடன் சேர்ந்தால் மட்டுமே படிக்கப்படும்.

மதிப்பு விளக்கம் செயல்படுத்துவது
"auto" உரையில் பதிலளிப்பதா அல்லது tool-ஐ அழைப்பதா என்பதை மாடல் முடிவு செய்யும். இதுவே இயல்புநிலை. அனைத்து மாடல்கள்
"required" பதில் குறைந்தது ஒரு tool-ஐ அழைக்கும். ஹோஸ்ட் செய்யப்பட்ட 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"}
குறைந்தது ஒரு tool-ஐ அழை "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. tool அழைப்புகள் இல்லாத சுற்றுக்கு, tools இல்லாமல் கோரிக்கையை அனுப்புங்கள்.

பதிலில் tool அழைப்புகள்

புலம் வகை விளக்கம்
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 arguments ஒரு JSON string ஆக, எதுவும் இல்லையென்றால் "{}". பயன்படுத்தும் முன் அதை parse செய்யுங்கள்.
message.content string | null பதிலில் அழைப்புகள் மட்டுமே இருந்தால் null. ஹோஸ்ட் செய்யப்பட்ட open-weight மாடல்கள் அழைப்புகளுக்குப் பக்கத்தில் உரையையும் தரலாம்; Shannon மாடல்கள் null தரும்.

ஒவ்வொரு வடிவத்திலும் அதே அழைப்பு. /v1/responses-ல் அது output-ன் function_call உருப்படி, arguments JSON string ஆக. /v1/messages-ல் அது tool_use content block; அதன் input ஒரு JSON object, அதன் 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 மாடல்கள் தனித்தனி அழைப்பை ஒருமுறை மட்டுமே தரும்: ஒரே பெயரும் ஒரே arguments-ம் கொண்ட இரண்டு அழைப்புகள் ஒன்றாக வந்து சேரும்.

Stream செய்யப்படும் tool அழைப்புகள்

stream: true உடன், அழைப்பு ஒரே துண்டாக வந்து சேரும்: chunk முழு arguments string-ஐக் கொண்டிருக்கும், எனவே இணைக்க வேண்டிய துண்டுகள் இல்லை. 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
    }
  ]
}
Endpoint வந்து சேர்வது
/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 (முழு string), response.function_call_arguments.done, response.output_item.done.
/v1/messages ஒவ்வொரு அழைப்புக்கும்: content_block_start (காலி input கொண்ட tool_use block), ஒரு content_block_delta (அதன் input_json_delta.partial_json முழு arguments உரை), 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 கொண்ட stream கோரிக்கை தன் பதில் உரையை சுற்றின் முடிவில் ஒரே 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.
  • முடிவு என்பது உரை. object-ஐ content-க்கு (/v1/responses-ல் output) JSON string ஆக மாற்றுங்கள். /v1/messages-ல் tool_result block-ன் content ஒரு string அல்லது உரை blocks-ன் பட்டியல்.
  • assistant சுற்றில், function.arguments வந்தபடியே JSON string ஆகவே இருக்கும்.
  • உரையாடல் ஒரு tool முடிவுடன் முடியலாம். புதிய பயனர் செய்தி தேவையில்லை: மாடல் முடிவிலிருந்து தொடரும்.
  • உங்கள் செயல்பாடு தோல்வியடைந்தால், தோல்வியை முடிவு உரையாக அனுப்புங்கள். மாடல் அதைத் தெரிவிக்கலாம் அல்லது வேறு அழைப்பைக் கேட்கலாம்.

Schema keywords

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 மூன்று endpoint-களிலும் இந்தத் துணைக் கணத்தைப் பெறுகின்றன:

கையாளும் முறை Keywords
அனுப்பியபடியே படிக்கப்படுபவை கீழ்வரிசைகளில் பெயரிடப்படாத ஒவ்வொரு keyword-ம், எடுத்துக்காட்டாக 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-ன் பிற மதிப்புகள்.

நடத்தையும் வரம்புகளும்

  • tools எண்ணிக்கைக்கும் சுற்றுகளின் எண்ணிக்கைக்கும் API அதிகபட்சம் எதுவும் நிர்ணயிக்கவில்லை.
  • கோரிக்கை body 32 MiB வரை இருக்கலாம், முடிவுகளுடன் உரையாடல் மாடலின் context window-வுக்குள் பொருந்த வேண்டும்.
  • கோரிக்கையில் tools இருக்கும்போது, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite மற்றும் shannon-2-pro இயல்புநிலை temperature 0.2-ஐப் பயன்படுத்தும். வேறு மதிப்பை அமைக்க temperature அனுப்புங்கள்.
  • ஒவ்வொரு சுற்றும் தனிக் கோரிக்கை: மற்ற கோரிக்கைகளைப் போலவே அது உங்கள் இருப்பிலிருந்து எடுக்கும், ஃப்ளட் பாதுகாப்பிலும் கணக்கில் சேரும். வரம்புகளும் இருப்பும்

பிழைகள்

tool அழைப்பு என்பது நிலை 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 ஒரு array அல்ல, அல்லது வேறொரு புலத்தின் JSON வகை தவறு.
413 invalid_request_error Failed to buffer the request body: … கோரிக்கை body 32 MiB-ஐ விடப் பெரியது. பிழையில் code: "request_too_large" இருக்கும்.

arguments-ஐ மாடல் எழுதுகிறது. எந்த வெளி உள்ளீட்டையும் சரிபார்ப்பதுபோல, செயல்பாட்டை இயக்கும் முன் உங்கள் schema-வுடன் அவற்றைச் சரிபாருங்கள்.

அங்கீகாரம், இருப்பு மற்றும் சர்வர் பிழைகள் ஒவ்வொரு கோரிக்கைக்கும் உள்ளவையே. கையாளுவதில் பிழை