අන්තර්ගතයට යන්න
කාර්ය කැඳවීම

කාර්ය කැඳවීම

ඉල්ලීමේ ඔබේ functions විස්තර කරන්න, එවිට model එක සිදු කිරීමට අවශ්‍ය calls සමඟ පිළිතුරු දෙයි. ඔබේ code එක ඒවා ක්‍රියාත්මක කර ප්‍රතිඵල ආපසු යවයි: API එක tool calls ආපසු දෙන අතර tool එකක් තනිවම ක්‍රියාත්මක නොකරයි.

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

මෙම පිටුවේ නියැදි /v1/chat/completions භාවිතා කරයි. එම loop එකම /v1/responses සහ /v1/messages හි ද ධාවනය වේ; format එකක් යමක් වෙනස් ලෙස ලියන තැන්වල, පහත කොටස් තුනම පෙන්වයි.

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)

පළමු පිළිතුර ප්‍රශ්නයට පිළිතුරු නොදෙයි. එය call එකක් ඉල්ලයි:

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 සමඟ model එකට ඉල්ලිය හැකි functions ලැයිස්තුව වන tools යවන්න.
2 Model එක පිළිතුර tool_calls සහ finish_reason: "tool_calls" රැගෙන යයි. සෑම call එකක්ම function එකක් නම් කර එහි arguments දෙයි.
3 ඔබ සෑම call එකකම arguments parse කර ඔබේ function එක ක්‍රියාත්මක කරන්න.
4 ඔබ Assistant පණිවිඩය සහ call එකකට එක tool පණිවිඩය බැගින් messages වලට එකතු කර, එම tools සමඟම ඉල්ලීම නැවත යවන්න.
5 Model එක Model එක finish_reason: "stop" සමඟ පෙළෙන් පිළිතුරු දෙයි, නැතහොත් තවත් calls ඉල්ලයි. එම අවස්ථාවේදී 3 පියවරට ආපසු යන්න.

එක ඉල්ලීමක් යනු එක model turn එකකි. API එක ඉල්ලීම් අතර සංවාදයක් තබා නොගන්නා අතර වට ගණනක් නියම නොකරයි: messages තබාගෙන කවදා නතර කරන්නේදැයි තීරණය කරන්නේ ඔබේ code එකයි.

Tools අර්ථ දැක්වීම

tools යනු function එකකට එක entry බැගින් ඇති array එකකි. නාමාවලියේ සෑම model එකක්ම එය පිළිගනී; GET /v1/models සෑම id එකකටම capabilities.tools: true වාර්තා කරයි.

Field වර්ගය විස්තරය
type string සෑම විටම function.
function.name string Model එක මෙම function එක ඉල්ලන විට භාවිතා කරන නම. අවශ්‍යයි.
function.description string Function එක කරන දේ, සරල භාෂාවෙන්.
function.parameters object Arguments ඉහළින් type: "object" සහිත JSON Schema එකක් ලෙස. පහත Schema keywords බලන්න.

සෑම endpoint එකකටම tool එකක් ලියන්නේ කෙසේද යන්න ගැන තමන්ගේම ආකාරයක් ඇත. ඔබ call කරන 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 මගින් model එකට tool එකක් call කළ හැකිද, නැතහොත් කළ යුතුද යන්න කියයි. එය කියවන්නේ tools සමඟ පමණි.

අගය විස්තරය යොදන්නේ
"auto" පෙළෙන් පිළිතුරු දෙනවාද tool එකක් call කරනවාද යන්න model එක තීරණය කරයි. මෙය පෙරනිමියයි. සියලු models
"required" පිළිතුර අවම වශයෙන් එක tool එකක් call කරයි. අපගේ සේවාදායකවල ධාවනය වන open-weight models
{"type": "function", "function": {"name": "get_weather"}} පිළිතුර මෙම function එක call කරයි. නම tools හි ඇති functions වලින් එකක් විය යුතුය. වෙනත් functions වලට calls පිළිතුරෙන් ඉවත් කෙරේ. අපගේ සේවාදායකවල ධාවනය වන open-weight models

Shannon models (shannon-*) auto සමඟ මෙන් සෑම ඉල්ලීමකදීම තීරණය කරයි.

required හෝ නම් කළ function එකක් සමඟ, tool_calls කියවීමට පෙර finish_reason කියවන්න. Model එක call එකක් නිපදවන්නේ නැති විට, පිළිතුර finish_reason: "stop" සහිත පෙළ පිළිතුරක් වේ.

තේරුම /v1/chat/completions /v1/responses /v1/messages
Model එක තීරණය කරයි "auto" "auto" {"type": "auto"}
අවම වශයෙන් එක tool එකක් call කරන්න "required" "required" {"type": "any"}
නම් කළ එක function එකක් call කරන්න {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

අනුකූලතාව සඳහා පිළිගනී: tool_choice: "none" සහ parallel_tool_calls. Tool calls නැති turn එකක් සඳහා, ඉල්ලීම tools නොමැතිව යවන්න.

පිළිතුරේ tool calls

Field වර්ගය විස්තරය
finish_reason string පිළිතුරේ අවම වශයෙන් එක call එකක් ඇති විට tool_calls.
message.tool_calls array Call එකකට එක entry බැගින්. Model එක call එකක් ඉල්ලූ විට පමණක් field එක ඇත.
tool_calls[].id string call_ ට පසුව hexadecimal අක්ෂර 32ක්. ප්‍රතිඵලය සමඟ එය tool_call_id ලෙස ආපසු යවන්න.
tool_calls[].type string සෑම විටම function.
tool_calls[].function.name string ක්‍රියාත්මක කළ යුතු function එක.
tool_calls[].function.arguments string Arguments JSON string එකක් ලෙස, නොමැති විට "{}". භාවිතයට පෙර එය parse කරන්න.
message.content string | null පිළිතුරේ calls පමණක් ඇති විට null. අපගේ සේවාදායකවල ධාවනය වන open-weight models වලට calls අසල පෙළ ආපසු දිය හැක; Shannon models null ආපසු දෙයි.

එම call එකම සෑම format එකකම. /v1/responses හි එය output හි function_call item එකකි, arguments JSON string එකක් ලෙස. /v1/messages හි එය input JSON object එකක් වන tool_use content block එකකි, එහි 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\"}"
        }
      }
    ]
  }
}

එක turn එකක calls කිහිපයක්

පිළිතුරක calls කිහිපයක් තිබිය හැක. ඒ සියල්ලම ක්‍රියාත්මක කර, ඊළඟ ඉල්ලීමේදී ඒ සෑම එකකටම තමන්ගේම tool_call_id සමඟ call එකකට එක ප්‍රතිඵලය බැගින් යවන්න.

අපගේ සේවාදායකවල ධාවනය වන open-weight models සෑම වෙනස් call එකක්ම එක වරක් ආපසු දෙයි: එකම නම සහ එකම arguments ඇති calls දෙකක් එකක් ලෙස පැමිණේ.

Stream කළ tool calls

stream: true සමඟ, call එකක් එකම කොටසකින් පැමිණේ: chunk එකේ සම්පූර්ණ arguments string එක ඇත, එබැවින් සම්බන්ධ කිරීමට කොටස් නැත. index turn එකේ calls 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 Call එකකට එක chat.completion.chunk බැගින්, call එක delta.tool_calls[0] හි. අවසාන chunk එකේ finish_reason: "tool_calls" සහ usage ඇත.
/v1/responses Call එකකට: response.output_item.added (හිස් arguments සහිත function_call item එකක්), response.function_call_arguments.delta (සම්පූර්ණ string එක), response.function_call_arguments.done, response.output_item.done.
/v1/messages Call එකකට: content_block_start (හිස් input සහිත tool_use block එකක්), input_json_delta.partial_json සම්පූර්ණ arguments පෙළ වන එක content_block_delta එකක්, 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 කළ ඉල්ලීමක් එහි පිළිතුරේ පෙළ turn එකේ අවසානයේ එක content delta එකකින් ලබා දෙයි. ස්ට්‍රීමිං

ප්‍රතිඵල ආපසු යැවීම

දෙවන ඉල්ලීම සංවාදය නැවත ලියා දේවල් දෙකක් එකතු කරයි: calls ඉල්ලූ assistant turn එක, සහ call එකකට එක ප්‍රතිඵලය.

{
  "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 turn එක ප්‍රතිඵලවලට පෙර ඔබට ලැබුණු ආකාරයටම ආපසු යවන්න. සෑම ප්‍රතිඵලයක්ම එහි call එකට id මගින් ගැළපේ: /v1/chat/completions හි tool_call_id, /v1/responses හි call_id, /v1/messages හි tool_use_id.
  • ප්‍රතිඵලයක් යනු පෙළකි. Object එකක් content සඳහා (/v1/responses හි output) JSON string එකකට serialise කරන්න. /v1/messages හි tool_result block එකක content string එකක් හෝ text blocks ලැයිස්තුවක් වේ.
  • Assistant turn එකේ, function.arguments එය පැමිණි ආකාරයටම JSON string එකක් ලෙස පවතී.
  • සංවාදය tool ප්‍රතිඵලයකින් අවසන් විය හැක. නව user පණිවිඩයක් අවශ්‍ය නැත: model එක ප්‍රතිඵලයෙන් දිගටම කරගෙන යයි.
  • ඔබේ function එක අසාර්ථක වූ විට, අසාර්ථකත්වය ප්‍රතිඵල පෙළ ලෙස යවන්න. එවිට model එකට එය වාර්තා කිරීමට හෝ වෙනත් call එකක් ඉල්ලීමට හැක.

Schema මූල පද

parameters (/v1/messages හි input_schema) යනු JSON Schema එකකි. Shannon 3 පවුල (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) සහ අපගේ සේවාදායකවල ධාවනය වන open-weight models එය ඔබ යවන ආකාරයටම ලබා ගනී.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro සහ shannon-coder-1 endpoints තුනේම මෙම උප කුලකය ලබා ගනී:

සැලකීම මූල පද (Keywords)
යැවූ ආකාරයටම කියවයි පහත පේළිවල නම් නොකළ සෑම මූල පදයක්ම, උදාහරණයක් ලෙස type, properties, required, items, enum, description, minimum, maximum, anyOf සහ allOf, schema එකේ සෑම මට්ටමකම.
format int32, int64, float, double, byte, date, date-time සහ enum යන අගයන් සඳහා කියවයි.
oneOf anyOf ලෙස කියවයි.
මෙම models වලට ලැබෙන 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 එක tools වල උපරිම සංඛ්‍යාවක් හෝ වටවල උපරිම සංඛ්‍යාවක් නියම කරන්නේ නැත.
  • ඉල්ලීමේ body එක 32 MiB දක්වා විය හැකි අතර, ප්‍රතිඵල සහිත සංවාදය model එකේ context window එකට ගැළපිය යුතුය.
  • ඉල්ලීමක tools ඇති විට, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite සහ shannon-2-pro පෙරනිමි temperature 0.2 භාවිතා කරයි. වෙනත් අගයක් සැකසීමට temperature යවන්න.
  • සෑම වටයක්ම ඊට ම අයත් ඉල්ලීමකි: එය ඔබේ ශේෂයෙන් අඩු කරන අතර වෙනත් ඕනෑම ඉල්ලීමක් මෙන් flood protection වෙත ගණන් ගැනේ. සීමා සහ ශේෂය

දෝෂ

Tool call එකක් යනු status 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 එකක් නොවේ, නැතහොත් වෙනත් field එකක JSON type එක වැරදිය.
413 invalid_request_error Failed to buffer the request body: … ඉල්ලීමේ body එක 32 MiB ට වඩා විශාලය. දෝෂයේ code: "request_too_large" ඇත.

Arguments ලියන්නේ model එකයි. ඕනෑම පිටත input එකක් පරීක්ෂා කරන ආකාරයටම, function එක ක්‍රියාත්මක කිරීමට පෙර ඒවා ඔබේ schema එකට එරෙහිව පරීක්ෂා කරන්න.

සත්‍යාපනය, ශේෂය සහ server දෝෂ සෑම ඉල්ලීමකටම මෙන්ම වේ. දෝෂ