ຂ້າມໄປຫາເນື້ອຫາ
ການເອີ້ນຟັງຊັນ

ການເອີ້ນຟັງຊັນ

ອະທິບາຍ function ຂອງທ່ານໃນຄຳຮ້ອງຂໍ ແລ້ວ model ຈະຕອບດ້ວຍການເອີ້ນທີ່ມັນຕ້ອງການ. ໂຄ້ດຂອງທ່ານຮັນມັນ ແລະ ສົ່ງຜົນລັບກັບຄືນ: 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, ລາຍຊື່ function ທີ່ model ອາດຂໍ.
2 Model ຄຳຕອບມີ tool_calls ແລະ finish_reason: "tool_calls". ແຕ່ລະການເອີ້ນລະບຸຊື່ function ແລະ ໃຫ້ arguments ຂອງມັນ.
3 ທ່ານ ແຕກ (parse) arguments ຂອງແຕ່ລະການເອີ້ນ ແລ້ວຮັນ function ຂອງທ່ານ.
4 ທ່ານ ເພີ່ມຂໍ້ຄວາມ assistant ແລະ ຂໍ້ຄວາມ tool ໜຶ່ງອັນຕໍ່ການເອີ້ນເຂົ້າໃນ messages, ແລ້ວສົ່ງຄຳຮ້ອງຂໍອີກດ້ວຍ tools ດຽວກັນ.
5 Model model ຕອບເປັນຂໍ້ຄວາມດ້ວຍ finish_reason: "stop", ຫຼື ຂໍການເອີ້ນເພີ່ມ. ໃນກໍລະນີນັ້ນໃຫ້ກັບໄປຂັ້ນຕອນ 3.

ໜຶ່ງຄຳຮ້ອງຂໍແມ່ນໜຶ່ງຮອບຂອງ model. API ບໍ່ເກັບການສົນທະນາລະຫວ່າງຄຳຮ້ອງຂໍ ແລະ ບໍ່ກຳນົດຈຳນວນຮອບ: ໂຄ້ດຂອງທ່ານເກັບ messages ແລະ ຕັດສິນໃຈວ່າຈະຢຸດເມື່ອໃດ.

ການກຳນົດ tool

tools ແມ່ນ array ທີ່ມີໜຶ່ງລາຍການຕໍ່ໜຶ່ງ function. ທຸກ model ໃນລາຍການຮັບມັນ; GET /v1/models ລາຍງານ capabilities.tools: true ສຳລັບທຸກ id.

ຟີລດ໌ ປະເພດ ຄຳອະທິບາຍ
type string ເປັນ function ສະເໝີ.
function.name string ຊື່ທີ່ model ໃຊ້ເມື່ອຂໍ function ນີ້. ຈຳເປັນ.
function.description string function ເຮັດຫຍັງ, ດ້ວຍພາສາທຳມະດາ.
function.parameters object arguments ເປັນ 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 ບອກວ່າ model ອາດ ຫຼື ຕ້ອງເອີ້ນ tool ຫຼືບໍ່. ມັນຖືກອ່ານພ້ອມກັບ tools ເທົ່ານັ້ນ.

ຄ່າ ຄຳອະທິບາຍ ໃຊ້ໂດຍ
"auto" model ຕັດສິນໃຈເອງວ່າຈະຕອບເປັນຂໍ້ຄວາມ ຫຼື ເອີ້ນ tool. ນີ້ແມ່ນຄ່າເລີ່ມຕົ້ນ. ທຸກ model
"required" ຄຳຕອບເອີ້ນ tool ຢ່າງນ້ອຍໜຶ່ງອັນ. Hosted open-weight models
{"type": "function", "function": {"name": "get_weather"}} ຄຳຕອບເອີ້ນ function ນີ້. ຊື່ຕ້ອງເປັນໜຶ່ງໃນ function ໃນ tools. ການເອີ້ນ function ອື່ນຈະຖືກຕັດອອກຈາກຄຳຕອບ. Hosted open-weight models

model Shannon (shannon-*) ຕັດສິນໃຈໃນທຸກຄຳຮ້ອງຂໍ, ຄືກັບ auto.

ກັບ required ຫຼື function ທີ່ລະບຸຊື່, ໃຫ້ອ່ານ finish_reason ກ່ອນອ່ານ tool_calls. ເມື່ອ model ບໍ່ສ້າງການເອີ້ນ, ຄຳຕອບຈະເປັນຂໍ້ຄວາມພ້ອມ 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, ໃຫ້ສົ່ງຄຳຮ້ອງຂໍໂດຍບໍ່ມີ tools.

ການເອີ້ນ tool ໃນຄຳຕອບ

ຟີລດ໌ ປະເພດ ຄຳອະທິບາຍ
finish_reason string tool_calls ເມື່ອຄຳຕອບມີການເອີ້ນຢ່າງນ້ອຍໜຶ່ງອັນ.
message.tool_calls array ໜຶ່ງລາຍການຕໍ່ໜຶ່ງການເອີ້ນ. ຟີລດ໌ນີ້ມີສະເພາະເມື່ອ model ຂໍການເອີ້ນ.
tool_calls[].id string call_ ຕາມດ້ວຍຕົວອັກສອນເລກຖານສິບຫົກ 32 ຕົວ. ສົ່ງມັນກັບຄືນເປັນ tool_call_id ພ້ອມຜົນລັບ.
tool_calls[].type string ເປັນ function ສະເໝີ.
tool_calls[].function.name string function ທີ່ຕ້ອງຮັນ.
tool_calls[].function.arguments string arguments ເປັນ string JSON, ເປັນ "{}" ເມື່ອບໍ່ມີ. ແຕກ (parse) ມັນກ່ອນໃຊ້.
message.content string | null ເປັນ null ເມື່ອຄຳຕອບມີແຕ່ການເອີ້ນ. Hosted open-weight models ສົ່ງຂໍ້ຄວາມຄຽງຄູ່ກັບການເອີ້ນໄດ້; model Shannon ສົ່ງ null.

ການເອີ້ນດຽວກັນໃນແຕ່ລະຮູບແບບ. ໃນ /v1/responses ມັນເປັນລາຍການ function_call ຂອງ output, ມີ arguments ເປັນ string JSON. ໃນ /v1/messages ມັນເປັນ content block tool_use ທີ່ input ເປັນ object 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 ຂອງຕົນເອງ, ໃນຄຳຮ້ອງຂໍຖັດໄປ.

Hosted open-weight models ສົ່ງແຕ່ລະການເອີ້ນທີ່ແຕກຕ່າງກັນເທື່ອດຽວ: ສອງການເອີ້ນທີ່ມີຊື່ດຽວກັນ ແລະ arguments ດຽວກັນຈະມາເປັນອັນດຽວ.

ການເອີ້ນ 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 ເປັນຂໍ້ຄວາມ 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, ຄຳຮ້ອງຂໍແບບ stream ທີ່ມີ 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: tool_call_id ໃນ /v1/chat/completions, call_id ໃນ /v1/responses, tool_use_id ໃນ /v1/messages.
  • ຜົນລັບແມ່ນຂໍ້ຄວາມ. ແປງ object ເປັນ string JSON ສຳລັບ content (output ໃນ /v1/responses). ໃນ /v1/messages, content ຂອງ block tool_result ເປັນ string ຫຼື ລາຍການຂອງ block ຂໍ້ຄວາມ.
  • ໃນຮອບຂອງ assistant, function.arguments ຍັງເປັນ string JSON, ຄືກັນກັບທີ່ມາເຖິງ.
  • ການສົນທະນາອາດຈົບດ້ວຍຜົນລັບຂອງ tool. ບໍ່ຕ້ອງມີຂໍ້ຄວາມ user ໃໝ່: model ສືບຕໍ່ຈາກຜົນລັບ.
  • ເມື່ອ function ຂອງທ່ານລົ້ມເຫຼວ, ສົ່ງຄວາມລົ້ມເຫຼວເປັນຂໍ້ຄວາມຜົນລັບ. model ຈະລາຍງານມັນ ຫຼື ຂໍການເອີ້ນອື່ນໄດ້.

Keyword ຂອງ schema

parameters (input_schema ໃນ /v1/messages) ແມ່ນ JSON Schema. ຕະກູນ Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ແລະ hosted open-weight models ໄດ້ຮັບມັນຕາມທີ່ທ່ານສົ່ງ.

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 ທີ່ model ເຫຼົ່ານີ້ໄດ້ຮັບ $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 ສູງສຸດ ແລະ ບໍ່ກຳນົດຈຳນວນຮອບສູງສຸດ.
  • body ຂອງຄຳຮ້ອງຂໍໃຫຍ່ໄດ້ເຖິງ 32 MiB, ແລະ ການສົນທະນາພ້ອມຜົນລັບຕ້ອງພໍດີກັບ context window ຂອງ model.
  • ເມື່ອຄຳຮ້ອງຂໍມີ tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ແລະ shannon-2-pro ໃຊ້ temperature ເລີ່ມຕົ້ນ 0.2. ສົ່ງ temperature ເພື່ອຕັ້ງຄ່າອື່ນ.
  • ທຸກຮອບແມ່ນຄຳຮ້ອງຂໍແຍກຕ່າງຫາກ: ມັນຫັກຈາກ ຍອດເງິນ ຂອງທ່ານ ແລະ ນັບເຂົ້າ flood protection ຄືກັບຄຳຮ້ອງຂໍອື່ນ. ຂີດຈຳກັດ ແລະ ຍອດເງິນ

ຂໍ້ຜິດພາດ

ການເອີ້ນ tool ແມ່ນຄຳຕອບປົກກະຕິທີ່ມີ 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, ຫຼື ຟີລດ໌ອື່ນມີປະເພດ JSON ຜິດ.
413 invalid_request_error Failed to buffer the request body: … body ຂອງຄຳຮ້ອງຂໍໃຫຍ່ກວ່າ 32 MiB. ຂໍ້ຜິດພາດມີ code: "request_too_large".

model ເປັນຜູ້ຂຽນ arguments. ກວດສອບມັນກັບ schema ຂອງທ່ານກ່ອນຮັນ function, ຄືກັບທີ່ທ່ານກວດ input ຈາກພາຍນອກ.

ຂໍ້ຜິດພາດດ້ານການຢືນຢັນ, ຍອດເງິນ ແລະ server ແມ່ນຄືກັນກັບທຸກຄຳຮ້ອງຂໍ. ການຈັດການຂໍ້ຜິດພາດ