រំលងទៅមាតិកា
ការហៅមុខងារ

ការហៅមុខងារ

ពិពណ៌នា function របស់អ្នកក្នុង request ហើយម៉ូដែលឆ្លើយជាមួយការហៅដែលវាចង់ឱ្យធ្វើ។ កូដរបស់អ្នកដំណើរការវា ហើយផ្ញើលទ្ធផលត្រឡប់៖ API ត្រឡប់ការហៅ tool ហើយមិនដំណើរការ tool ដោយខ្លួនឯងទេ។

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 ជាបញ្ជី function ដែលម៉ូដែលអាចស្នើ។
2 ម៉ូដែល ចម្លើយមាន tool_calls និង finish_reason: "tool_calls"។ ការហៅនីមួយៗដាក់ឈ្មោះ function និងផ្តល់អាគុយម៉ង់របស់វា។
3 អ្នក បំលែង arguments នៃការហៅនីមួយៗ ហើយដំណើរការ function របស់អ្នក។
4 អ្នក បន្ថែមសារ assistant និងសារ tool មួយក្នុងមួយការហៅទៅ messages បន្ទាប់មកផ្ញើ request ម្តងទៀតជាមួយ tools ដូចគ្នា។
5 ម៉ូដែល ម៉ូដែលឆ្លើយជាអត្ថបទជាមួយ finish_reason: "stop" ឬស្នើការហៅបន្ថែម។ ក្នុងករណីនោះសូមត្រឡប់ទៅជំហាន 3។

request មួយគឺជាវគ្គម៉ូដែលមួយ។ API មិនរក្សាការសន្ទនារវាង request ហើយមិនកំណត់ចំនួនជុំទេ៖ កូដរបស់អ្នករក្សា messages ហើយសម្រេចថាពេលណាត្រូវឈប់។

ការកំណត់ tools

tools គឺជាអារេដែលមានមួយធាតុក្នុងមួយ function។ គ្រប់ម៉ូដែលក្នុងកាតាឡុកទទួលវា; GET /v1/models រាយការណ៍ capabilities.tools: true សម្រាប់គ្រប់ id។

Field ប្រភេទ ការពិពណ៌នា
type string ជានិច្ចជា function។
function.name string ឈ្មោះដែលម៉ូដែលប្រើនៅពេលវាស្នើ function នេះ។ ត្រូវការ។
function.description string អ្វីដែល function ធ្វើ ក្នុងភាសាធម្មតា។
function.parameters object អាគុយម៉ង់ជា JSON Schema ដែលមាន type: "object" នៅកំពូល។ សូមមើល Keyword របស់ schema ខាងក្រោម។

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 ប្រាប់ថាម៉ូដែលអាច ឬត្រូវតែហៅ tool។ វាត្រូវបានអានតែជាមួយ tools ប៉ុណ្ណោះ។

តម្លៃ ការពិពណ៌នា អនុវត្តដោយ
"auto" ម៉ូដែលសម្រេចចិត្តថាត្រូវឆ្លើយជាអត្ថបទ ឬហៅ tool។ នេះជាលំនាំដើម។ គ្រប់ម៉ូដែល
"required" ចម្លើយហៅ tool យ៉ាងហោចណាស់មួយ។ ម៉ូដែល open-weight ដែលបង្ហោះ
{"type": "function", "function": {"name": "get_weather"}} ចម្លើយហៅ function នេះ។ ឈ្មោះត្រូវតែជា function មួយក្នុង tools។ ការហៅ function ផ្សេងត្រូវបានទុកចោលពីចម្លើយ។ ម៉ូដែល open-weight ដែលបង្ហោះ

ម៉ូដែល Shannon (shannon-*) សម្រេចចិត្តក្នុងរាល់ request ដូចជាមួយ auto។

ជាមួយ required ឬ function ដែលបានដាក់ឈ្មោះ សូមអាន finish_reason មុនអាន tool_calls។ នៅពេលម៉ូដែលមិនបង្កើតការហៅ ចម្លើយគឺជាចម្លើយអត្ថបទដែលមាន finish_reason: "stop"។

អត្ថន័យ /v1/chat/completions /v1/responses /v1/messages
ម៉ូដែលសម្រេចចិត្ត "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 សូមផ្ញើ request ដោយគ្មាន tools។

ការហៅ tool ក្នុងចម្លើយ

Field ប្រភេទ ការពិពណ៌នា
finish_reason string tool_calls នៅពេលចម្លើយមានការហៅយ៉ាងហោចណាស់មួយ។
message.tool_calls array មួយធាតុក្នុងមួយការហៅ។ 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 អាគុយម៉ង់ជា JSON string គឺ "{}" នៅពេលគ្មាន។ សូមបំលែងវាមុនប្រើ។
message.content string | null null នៅពេលចម្លើយមានតែការហៅ។ ម៉ូដែល open-weight ដែលបង្ហោះអាចត្រឡប់អត្ថបទក្បែរការហៅ; ម៉ូដែល Shannon ត្រឡប់ null។

ការហៅដូចគ្នាក្នុងទ្រង់ទ្រាយនីមួយៗ។ លើ /v1/responses វាជាធាតុ function_call នៃ output ដែលមាន arguments ជា JSON string។ លើ /v1/messages វាជា content block tool_use ដែល 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 ផ្ទាល់ខ្លួន ក្នុង request បន្ទាប់។

ម៉ូដែល open-weight ដែលបង្ហោះ ត្រឡប់ការហៅដែលខុសគ្នានីមួយៗម្តង៖ ការហៅពីរដែលមានឈ្មោះដូចគ្នា និងអាគុយម៉ង់ដូចគ្នាមកដល់ជាមួយ។

ការហៅ tool ជា stream

ជាមួយ stream: true ការហៅមកដល់ជាដុំតែមួយ៖ chunk មាន string 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
    }
  ]
}
Endpoint អ្វីដែលមកដល់
/v1/chat/completions មួយ chat.completion.chunk ក្នុងមួយការហៅ ដោយមានការហៅក្នុង delta.tool_calls[0]។ chunk ចុងក្រោយមាន finish_reason: "tool_calls" និង usage។
/v1/responses ក្នុងមួយការហៅ៖ response.output_item.added (ធាតុ function_call ដែល arguments ទទេ), response.function_call_arguments.delta (string ទាំងមូល), response.function_call_arguments.done, response.output_item.done។
/v1/messages ក្នុងមួយការហៅ៖ content_block_start (block tool_use ដែល input ទទេ), 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 request ជា stream ដែលមាន tools ប្រគល់អត្ថបទចម្លើយរបស់វាក្នុង content delta តែមួយនៅចុងវគ្គ។ ស្ទ្រីម

ការផ្ញើលទ្ធផលត្រឡប់

request ទីពីរនិយាយការសន្ទនាម្តងទៀត ហើយបន្ថែមពីរយ៉ាង៖ វគ្គ 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៖ tool_call_id លើ /v1/chat/completions, call_id លើ /v1/responses, tool_use_id លើ /v1/messages។
  • លទ្ធផលគឺជាអត្ថបទ។ សូមបំលែង object ទៅជា JSON string សម្រាប់ content (output លើ /v1/responses)។ លើ /v1/messages content នៃ block tool_result គឺជា string ឬបញ្ជីនៃ text block។
  • ក្នុងវគ្គ assistant function.arguments នៅតែជា JSON string ដូចដែលវាមកដល់។
  • ការសន្ទនាអាចបញ្ចប់ដោយលទ្ធផល tool។ មិនត្រូវការសារ user ថ្មីទេ៖ ម៉ូដែលបន្តពីលទ្ធផល។
  • នៅពេល function របស់អ្នកបរាជ័យ សូមផ្ញើការបរាជ័យជាអត្ថបទលទ្ធផល។ បន្ទាប់មកម៉ូដែលអាចរាយការណ៍វា ឬស្នើការហៅផ្សេង។

Keyword របស់ schema

parameters (input_schema លើ /v1/messages) គឺជា 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 ទាំងបី៖

ការដោះស្រាយ Keyword
អានតាមដែលបានផ្ញើ រាល់ 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។

ឥរិយាបថ និងដែនកំណត់

  • API មិនកំណត់ចំនួន tool ច្រើនបំផុត ឬចំនួនជុំច្រើនបំផុតទេ។
  • ខ្លឹមសារ request អាចមានទំហំរហូតដល់ 32 MiB ហើយការសន្ទនាជាមួយលទ្ធផលរបស់វាត្រូវតែសមក្នុង context window របស់ម៉ូដែល។
  • នៅពេល request មាន tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite និង shannon-2-pro ប្រើ temperature លំនាំដើម 0.2។ ផ្ញើ temperature ដើម្បីកំណត់តម្លៃផ្សេង។
  • រាល់ជុំគឺជា request ផ្ទាល់ខ្លួន៖ វាដកពីសមតុល្យរបស់អ្នក ហើយរាប់ក្នុង flood protection ដូច request ផ្សេងទៀត។ ដែនកំណត់ និងសមតុល្យ

កំហុស

ការហៅ tool គឺជាចម្លើយធម្មតាដែលមានស្ថានភាព 200។ កំហុសទាំងនេះទាក់ទងនឹង request ខ្លួនឯង៖

ស្ថានភាព ប្រភេទ សារ ពេលណា
400 invalid_request_error unknown model: <id> model មិនមែនជា id ក្នុងបញ្ជីដែលបានផ្សព្វផ្សាយទេ។
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools មិនមែនជាអារេ ឬ field ផ្សេងមានប្រភេទ JSON មិនត្រឹមត្រូវ។
413 invalid_request_error Failed to buffer the request body: … ខ្លឹមសារ request ធំជាង 32 MiB។ កំហុសមាន code: "request_too_large"។

ម៉ូដែលសរសេរអាគុយម៉ង់។ សូមពិនិត្យវាតាម schema របស់អ្នកមុនដំណើរការ function ដូចអ្នកពិនិត្យ input ពីខាងក្រៅណាមួយ។

កំហុសនៃការផ្ទៀងផ្ទាត់ សមតុល្យ និង server ដូចគ្នាសម្រាប់រាល់ request។ ការគ្រប់គ្រងកំហុស