အကြောင်းအရာသို့ ကျော်သွားရန်
လုပ်ဆောင်ချက် ခေါ်ဆိုမှု

လုပ်ဆောင်ချက် ခေါ်ဆိုမှု

request တွင် သင့် function များကို ဖော်ပြပါ၊ model က ခေါ်စေလိုသော calls များကို ပြန်ကြားမည်။ သင့် code က ၎င်းတို့ကို run ပြီး ရလဒ်များကို ပြန်ပို့သည်- API သည် tool calls များကို ပြန်ပေးပြီး tool ကို ကိုယ်တိုင် မ run ပါ။

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 နှင့်အတူ tools၊ model တောင်းဆိုနိုင်သော function များ၏ စာရင်းကို ပို့ပါ။
2 Model ပြန်ကြားချက်တွင် tool_calls နှင့် finish_reason: "tool_calls" ပါသည်။ call တစ်ခုစီသည် function တစ်ခုကို အမည်ပေးပြီး ၎င်း၏ arguments ကို ပေးသည်။
3 သင် call တစ်ခုစီ၏ arguments ကို parse လုပ်ပြီး သင့် function ကို run ပါ။
4 သင် assistant message နှင့် call တစ်ခုလျှင် tool message တစ်ခုကို messages သို့ ထည့်ပေါင်းပြီး တူညီသော tools ဖြင့် request ကို ပြန်ပို့ပါ။
5 Model model သည် finish_reason: "stop" ဖြင့် စာသားအဖြေ ဖြေသည်၊ သို့မဟုတ် calls ထပ်တောင်းသည်။ ထိုအခါ အဆင့် 3 သို့ ပြန်သွားပါ။

request တစ်ခုသည် model turn တစ်ခု ဖြစ်သည်။ API သည် request များအကြား စကားပြောဆိုမှုကို မသိမ်းဘဲ round အရေအတွက်ကိုလည်း မသတ်မှတ်ပါ- messages ကို သင့် code က ကိုင်ထားပြီး ဘယ်အချိန်ရပ်မည်ကို ဆုံးဖြတ်သည်။

Tools ကို သတ်မှတ်ခြင်း

tools သည် function တစ်ခုလျှင် entry တစ်ခုပါသော array ဖြစ်သည်။ catalogue ရှိ model တိုင်းက ၎င်းကို လက်ခံသည်၊ GET /v1/models သည် id တိုင်းအတွက် capabilities.tools: true ကို ဖော်ပြသည်။

Field Type ဖော်ပြချက်
type string အမြဲတမ်း function။
function.name string model သည် ဤ function ကို တောင်းဆိုသောအခါ အသုံးပြုသည့် အမည်။ လိုအပ်သည်။
function.description string function က ဘာလုပ်သည်ကို ရိုးရိုးဘာသာစကားဖြင့်။
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_choice သည် model က tool ကို ခေါ်ခွင့်ရှိသလား၊ ခေါ်ရမလားကို ပြောသည်။ ၎င်းကို tools နှင့်အတူသာ ဖတ်သည်။

တန်ဖိုး ဖော်ပြချက် အသုံးပြုသော model
"auto" model သည် စာသားဖြင့် ဖြေမလား tool ခေါ်မလား ဆုံးဖြတ်သည်။ ဤသည်မှာ default ဖြစ်သည်။ Model အားလုံး
"required" ပြန်ကြားချက်သည် tool တစ်ခုအနည်းဆုံး ခေါ်သည်။ Host လုပ်ထားသော open-weight မော်ဒယ်များ
{"type": "function", "function": {"name": "get_weather"}} ပြန်ကြားချက်သည် ဤ function ကို ခေါ်သည်။ အမည်သည် tools ထဲရှိ function များထဲမှ တစ်ခု ဖြစ်ရမည်။ အခြား function များသို့ ခေါ်ဆိုမှုများကို ပြန်ကြားချက်မှ ချန်လှပ်ထားသည်။ Host လုပ်ထားသော open-weight မော်ဒယ်များ

Shannon models (shannon-*) သည် auto ကဲ့သို့ request တိုင်းတွင် ကိုယ်တိုင် ဆုံးဖြတ်သည်။

required သို့မဟုတ် အမည်ပေးထားသော function ဖြင့် tool_calls ကို မဖတ်မီ finish_reason ကို အရင်ဖတ်ပါ။ model က call မထုတ်ပေးလျှင် ပြန်ကြားချက်သည် finish_reason: "stop" ပါသော စာသားအဖြေ ဖြစ်သည်။

အဓိပ္ပာယ် /v1/chat/completions /v1/responses /v1/messages
model က ဆုံးဖြတ်သည် "auto" "auto" {"type": "auto"}
tool တစ်ခုအနည်းဆုံး ခေါ်ပါ "required" "required" {"type": "any"}
အမည်ပေးထားသော function တစ်ခုကို ခေါ်ပါ {"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 မပါဘဲ request ကို ပို့ပါ။

ပြန်ကြားချက်ရှိ Tool calls

Field Type ဖော်ပြချက်
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 ခေါ်ဆိုပြီး run ရမည့် function ၏ အမည်။
tool_calls[].function.arguments string arguments ကို JSON string အဖြစ် ပေးသည်၊ မရှိလျှင် "{}"။ အသုံးမပြုမီ parse လုပ်ပါ။
message.content string | null ပြန်ကြားချက်တွင် calls သာ ပါလျှင် null။ Host လုပ်ထားသော open-weight models များသည် calls နှင့်အတူ စာသားကိုလည်း ပြန်ပေးနိုင်သည်၊ Shannon models များက null ပြန်ပေးသည်။

format တစ်ခုစီရှိ တူညီသော call။ /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 များစွာ ပါနိုင်သည်။ ၎င်းတို့အားလုံးကို run ပြီး နောက် request တွင် call တစ်ခုလျှင် ရလဒ်တစ်ခုကို ကိုယ်ပိုင် tool_call_id ဖြင့် ပို့ပါ။

Host လုပ်ထားသော open-weight models များသည် ကွဲပြားသော call တစ်ခုစီကို တစ်ကြိမ်သာ ပြန်ပေးသည်- အမည်နှင့် arguments တူညီသော calls နှစ်ခုသည် တစ်ခုအဖြစ် ရောက်လာသည်။

Stream လုပ်ထားသော tool calls

stream: true ဖြင့် call သည် တစ်စုတစ်စည်းတည်း ရောက်လာသည်- chunk တွင် arguments string အပြည့်အစုံ ပါသဖြင့် ပေါင်းစပ်ရန် အပိုင်းအစများ မရှိပါ။ index သည် turn ၏ calls များကို 0 မှ ရေတွက်သည်။

data: chunk တစ်ခု၊ format ချထားသည်
{
  "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 request သည် ၎င်း၏ အဖြေစာသားကို turn အဆုံးတွင် content delta တစ်ခုအဖြစ် ပေးပို့သည်။ စตรีမင်း

ရလဒ်များကို ပြန်ပို့ခြင်း

ဒုတိယ request သည် စကားပြောဆိုမှုကို ထပ်ဖော်ပြပြီး အရာနှစ်ခု ထပ်ထည့်သည်- 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 ကို လက်ခံရရှိသည့်အတိုင်း ပြန်ပို့ပါ။ ရလဒ်တစ်ခုစီကို id ဖြင့် ၎င်း၏ call နှင့် တွဲသည်- /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 block များ၏ စာရင်း ဖြစ်သည်။
  • assistant turn တွင် function.arguments သည် ရောက်လာသည့်အတိုင်း JSON string အဖြစ် ဆက်ရှိနေသည်။
  • စကားပြောဆိုမှုသည် tool ရလဒ်ဖြင့် အဆုံးသတ်နိုင်သည်။ user message အသစ် မလိုအပ်ပါ- model သည် ရလဒ်မှ ဆက်လက်လုပ်ဆောင်သည်။
  • သင့် function မအောင်မြင်လျှင် ကျရှုံးမှုကို ရလဒ်စာသားအဖြစ် ပို့ပါ။ ထိုအခါ model က ၎င်းကို သတင်းပို့နိုင်သည် သို့မဟုတ် အခြား call တစ်ခု တောင်းနိုင်သည်။

Schema keywords

parameters (/v1/messages တွင် input_schema) သည် JSON Schema တစ်ခု ဖြစ်သည်။ Shannon 3 မိသားစု (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) နှင့် host လုပ်ထားသော open-weight models များသည် ၎င်းကို သင်ပို့သည့်အတိုင်း လက်ခံရရှိသည်။

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro နှင့် shannon-coder-1 တို့သည် endpoint သုံးခုလုံးတွင် ဤ subset ကို လက်ခံရရှိသည်-

ကိုင်တွယ်ပုံ 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 အဖြစ် ဖတ်သည်။
ဤ model များ လက်ခံရရှိသော 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 အရေအတွက်အများဆုံး သို့မဟုတ် round အရေအတွက်အများဆုံးကို မသတ်မှတ်ပါ။
  • request body သည် 32 MiB အထိ ရှိနိုင်ပြီး ရလဒ်များပါသော စကားပြောဆိုမှုသည် model ၏ context window ထဲ ဆန့်ရမည်။
  • request တွင် tools ပါလျှင် shannon-1.6-lite၊ shannon-1.6-pro၊ shannon-2-lite နှင့် shannon-2-pro တို့သည် default temperature 0.2 ကို သုံးသည်။ အခြားတန်ဖိုးလိုလျှင် temperature ကို ပို့ပါ။
  • အကြိမ်တိုင်းသည် သီးခြား request တစ်ခုဖြစ်သည်- ၎င်းသည် သင့်လက်ကျန်ငွေမှ နုတ်ယူပြီး အခြား request များကဲ့သို့ flood protection တွင် ရေတွက်သည်။ ကန့်သတ်ချက်များနှင့် လက်ကျန်ငွေ

အမှားများ

tool call သည် status 200 ပါသော ပုံမှန်ပြန်ကြားချက် ဖြစ်သည်။ ဤအမှားများသည် request ကိုယ်တိုင်နှင့် ဆိုင်သည်-

Status Type မက်ဆေ့ချ် ဖြစ်ပေါ်ချိန်
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: … request body သည် 32 MiB ထက် ပိုကြီးသည်။ အမှားတွင် code: "request_too_large" ပါသည်။

arguments ကို model က ရေးသည်။ အပြင်ဘက်မှ input မည်သည့်အရာကိုမဆို စစ်ဆေးသကဲ့သို့ function ကို မ run မီ သင့် schema နှင့် တိုက်စစ်ပါ။

Authentication၊ လက်ကျန်ငွေနှင့် server အမှားများသည် request တိုင်းနှင့် အတူတူပင်ဖြစ်သည်။ အမှားကိုင်တွယ်မှု