Tlola ho ea ho litaba
Mekhosi ya mesebetsi

Mekhosi ya mesebetsi

Hlalosa li-function tsa hau kopong mme model e araba ka likopo tseo e batlang li etsoa. Code ea hau e li etsa mme e romela liphetho hape: API e khutlisa likopo tsa tool mme ha e etse tool ka boeona.

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

Mehlala leqepheng lena e sebelisa /v1/chat/completions. Loop e tšoanang e sebetsa ho /v1/responses le /v1/messages; moo sebopeho se ngolang ntho ka tsela e fapaneng, likarolo tse ka tlase li bontša tse tharo kaofela.

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)

Karabo ea pele ha e arabe potso. E kopa kopo ea tool:

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}
  }
}

Ka mor'a hore u romele sephetho, karabo e latelang ke karabo e tloaelehileng: message.content e na le mongolo mme finish_reason ke stop.

Loop, mohato ka mohato

Mohato Mang Se etsahalang
1 Uena Romela messages hammoho le tools, lenane la li-function tseo model e ka li kopang.
2 Model Karabo e nka tool_calls le finish_reason: "tool_calls". Kopo e 'ngoe le e 'ngoe e reha function mme e fana ka li-argument tsa eona.
3 Uena Parse arguments ea kopo e 'ngoe le e 'ngoe mme u etse function ea hau.
4 Uena Eketsa molaetsa oa assistant le molaetsa o le mong oa tool ka kopo ho messages, ebe u romela kopo hape le tools tse tšoanang.
5 Model Model e araba ka mongolo le finish_reason: "stop", kapa e kopa likopo tse ling. Maemong ao khutlela ho mohato oa 3.

Kopo e le 'ngoe ke turn e le 'ngoe ea model. API ha e boloke moqoqo pakeng tsa likopo mme ha e beha palo ea li-round: code ea hau e tšoara messages mme e etsa qeto ea hore na e ema neng.

Ho hlalosa lisebelisoa

tools ke array e nang le entry e le 'ngoe ka function. Model e 'ngoe le e 'ngoe ea catalogue e e amohela; GET /v1/models e tlaleha capabilities.tools: true bakeng sa id e 'ngoe le e 'ngoe.

Field Mofuta Tlhaloso
type string Kamehla ke function.
function.name string Lebitso leo model e le sebelisang ha e kopa function ena. E hlokahala.
function.description string Seo function e se etsang, ka puo e bonolo.
function.parameters object Li-argument e le JSON Schema e nang le type: "object" holimo. Bona Mantsoe a bohlokoa a schema ka tlase.

Endpoint e 'ngoe le e 'ngoe e na le mokhoa oa eona oa ho ngola tool. Romela eo e leng ea endpoint eo u e bitsang:

{
  "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 e re ke hore na model e ka bitsa tool, kapa e tlameha ho e bitsa. E baloa feela hammoho le tools.

Boleng Tlhaloso E sebelisoa ke
"auto" Model e iketsetsa qeto ea hore na e arabe ka mongolo kapa e bitse tool. Ena ke default. Li-model tsohle
"required" Karabo e bitsa bonyane tool e le 'ngoe. Li-model tse hosted tsa open-weight
{"type": "function", "function": {"name": "get_weather"}} Karabo e bitsa function ena. Lebitso le tlameha ho ba le leng la li-function tse ho tools. Likopo tsa li-function tse ling li siuoa karabong. Li-model tse hosted tsa open-weight

Li-model tsa Shannon (shannon-*) li iketsetsa qeto kopong e 'ngoe le e 'ngoe, joalo ka ka auto.

Ka required kapa function e rehiloeng, bala finish_reason pele u bala tool_calls. Ha model e sa hlahise kopo, karabo ke karabo ea mongolo e nang le finish_reason: "stop".

Moelelo /v1/chat/completions /v1/responses /v1/messages
Model e iketsetsa qeto "auto" "auto" {"type": "auto"}
Bitsa bonyane tool e le 'ngoe "required" "required" {"type": "any"}
Bitsa function e le 'ngoe e rehiloeng {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Li amohelwa bakeng sa compatibility: tool_choice: "none" le parallel_tool_calls. Bakeng sa turn e se nang likopo tsa tool, romela kopo ntle le tools.

Likopo tsa tool karabong

Field Mofuta Tlhaloso
finish_reason string tool_calls ha karabo e nka bonyane kopo e le 'ngoe.
message.tool_calls array Entry e le 'ngoe ka kopo. Field e teng feela ha model e kopile kopo.
tool_calls[].id string call_ e latelwa ke litlhaku tse 32 tsa hexadecimal. E khutlisetse e le tool_call_id hammoho le sephetho.
tool_calls[].type string Kamehla ke function.
tool_calls[].function.name string Function e lokelang ho etsoa.
tool_calls[].function.arguments string Li-argument e le string ea JSON, "{}" ha ho e 'ngoe. E parse pele u e sebelisa.
message.content string | null null ha karabo e na le likopo feela. Li-model tse hosted tsa open-weight li ka khutlisa mongolo haufi le likopo; li-model tsa Shannon li khutlisa null.

Kopo e tšoanang sebopeho se seng le se seng. Ho /v1/responses ke ntho ea function_call ea output, e nang le arguments e le string ea JSON. Ho /v1/messages ke content block ea tool_use eo input ea eona e leng ntho ea JSON, id ea eona e qala ka toolu_, mme stop_reason ke 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\"}"
        }
      }
    ]
  }
}

Likopo tse ngata turn e le 'ngoe

Karabo e ka nka likopo tse ngata. Etsa e 'ngoe le e 'ngoe ea tsona mme u romele sephetho se le seng ka kopo, e 'ngoe le e 'ngoe e na le tool_call_id ea eona, kopong e latelang.

Li-model tse hosted tsa open-weight li khutlisa kopo e 'ngoe le e 'ngoe e ikhethang hang feela: likopo tse peli tse nang le lebitso le li-argument tse tšoanang li fihla e le e le 'ngoe.

Likopo tsa tool tsa streaming

Ka stream: true, kopo e fihla e le sekhechana se le seng: chunk e na le string eohle ea arguments, kahoo ha ho likhechana tseo u lokelang ho li kopanya. index e bala likopo tsa turn ho tloha ho 0.

data: chunk e le 'ngoe, e hlophisitsoeng
{
  "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 Seo se fihlang
/v1/chat/completions chat.completion.chunk e le 'ngoe ka kopo, e nang le kopo ho delta.tool_calls[0]. Chunk ea ho qetela e na le finish_reason: "tool_calls" le usage.
/v1/responses Ka kopo: response.output_item.added (ntho ea function_call e nang le arguments e se nang letho), response.function_call_arguments.delta (string eohle), response.function_call_arguments.done, response.output_item.done.
/v1/messages Ka kopo: content_block_start (block ea tool_use e nang le input e se nang letho), content_block_delta e le 'ngoe eo input_json_delta.partial_json ea eona e leng mongolo oohle oa li-argument, content_block_stop. Ebe message_delta e nka stop_reason: "tool_use".

Ho shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro le shannon-coder-1, kopo ea streaming e nang le tools e fana ka mongolo oa karabo ho content delta e le 'ngoe qetellong ea turn. Phallela

Ho romela liphetho hape

Kopo ea bobeli e pheta moqoqo mme e eketsa lintho tse peli: turn ea assistant e kopileng likopo, le sephetho se le seng ka kopo.

{
  "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\"}"
    }
  ]
}
  • Romela turn ea assistant hape joalo ka ha u e fumane, pele ho liphetho. Sephetho se seng le se seng se amanngoa le kopo ea sona ka id: tool_call_id ho /v1/chat/completions, call_id ho /v1/responses, tool_use_id ho /v1/messages.
  • Sephetho ke mongolo. Fetolela ntho ho string ea JSON bakeng sa content (output ho /v1/responses). Ho /v1/messages content ea block ea tool_result ke string kapa lenane la li-block tsa mongolo.
  • Turn-ng ea assistant, function.arguments e lula e le string ea JSON, hantle joalo ka ha e fihlile.
  • Moqoqo o ka fela ka sephetho sa tool. Ha ho hlokahale molaetsa o mocha oa user: model e tsoela pele ho tloha sephetho.
  • Ha function ea hau e hloleha, romela phoso e le mongolo oa sephetho. Model e ka e tlaleha kapa ea kopa kopo e 'ngoe.

Mantsoe a bohlokoa a schema

parameters (input_schema ho /v1/messages) ke JSON Schema. Lelapa la Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) le li-model tse hosted tsa open-weight li e amohela joalo ka ha u e romela.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro le shannon-coder-1 li amohela subset ena, ho li-endpoint tse tharo tsohle:

Tsela ea ho sebetsana le eona Mantsoe a bohlokoa
E baloa joalo ka ha e rometsoe Lentsoe le leng le le leng le sa rehoang mela e ka tlase, mohlala type, properties, required, items, enum, description, minimum, maximum, anyOf le allOf, boemong bo bong le bo bong ba schema.
format E baloa bakeng sa litekanyo int32, int64, float, double, byte, date, date-time le enum.
oneOf E baloa e le anyOf.
Hase karolo ea schema eo li-model tsena li e amohelang $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 le exclusiveMaximum ha e le linomoro; litekanyo tse ling tsa format.

Boitšoaro le meeli

  • API ha e beha palo e phahameng ea lisebelisoa kapa palo e phahameng ea li-round.
  • Body ea kopo e ka ba 32 MiB, mme moqoqo le liphetho tsa oona o tlameha ho kena ho context window ea model.
  • Ha kopo e na le tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite le shannon-2-pro li sebelisa temperature ea default ea 0.2. Romela temperature ho beha boleng bo bong.
  • Round e 'ngoe le e 'ngoe ke kopo ea eona: e ntša ho balance ea hau mme e baloa ho flood protection joalo ka kopo e 'ngoe le e 'ngoe. Meeli le balance

Liphoso

Kopo ea tool ke karabo e tloaelehileng e nang le boemo ba 200. Liphoso tsena li amana le kopo ka boeona:

Boemo Mofuta Molaetsa Neng
400 invalid_request_error unknown model: <id> model hase id ea lenane le phatlalalitsoeng.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools hase array, kapa field e ngoe e na le mofuta o fosahetseng oa JSON.
413 invalid_request_error Failed to buffer the request body: … Body ea kopo e kholo ho feta 32 MiB. Phoso e na le code: "request_too_large".

Model e ngola li-argument. Li hlahlobe ka schema ea hau pele u etsa function, joalo ka ha u ka hlahloba input efe kapa efe ea ka ntle.

Liphoso tsa netefatso, balance le server li tšoana le tsa kopo e 'ngoe le e 'ngoe. Diphoso