Mandrosoa any amin'ny votoaty
Antso fiasa

Antso fiasa

Faritano ao amin'ny fangatahana ny function-nao dia mamaly ny model amin'ny antso tiany atao. Ny kaody-nao no mampandeha azy ireo ary mandefa ny valiny: ny API dia mamerina tool calls fa tsy mampandeha tool izy ihany.

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

Ny ohatra amin'ity pejy ity dia mampiasa ny /v1/chat/completions. Ny loop mitovy no mandeha amin'ny /v1/responses sy /v1/messages; raha misy zavatra tsy mitovy ny fanoratana amin'ny endrika iray, ny fizarana etsy ambany dia mampiseho ny telo.

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)

Ny valiny voalohany dia tsy mamaly ny fanontaniana. Mangataka antso izy:

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

Rehefa alefanao ny valiny, ny valiny manaraka dia valiny mahazatra: ny message.content no misy ny soratra ary stop ny finish_reason.

Ny loop, dingana isan-dingana

Dingana Iza Izay mitranga
1 Ianao Alefaso ny messages miaraka amin'ny tools, ny lisitry ny function azon'ny model angatahana.
2 Model Ny valiny dia mitondra tool_calls sy finish_reason: "tool_calls". Ny antso tsirairay dia manonona function ary manome ny arguments-ny.
3 Ianao Parse-o ny arguments isaky ny antso ary ampandehano ny function-nao.
4 Ianao Ampio ny hafatra assistant sy hafatra tool iray isaky ny antso ao amin'ny messages, avy eo alefaso indray ny fangatahana miaraka amin'ny tools mitovy.
5 Model Mamaly amin'ny soratra miaraka amin'ny finish_reason: "stop" ny model, na mangataka antso hafa. Amin'izay dia miverena any amin'ny dingana 3.

Fangatahana iray dia fihodinan'ny model iray. Ny API dia tsy mitahiry resaka eo anelanelan'ny fangatahana ary tsy mametraka isa fihodinana: ny kaody-nao no mitazona ny messages ary mamaritra rehefa hijanona.

Famaritana ny tools

Ny tools dia array misy iray isaky ny function. Ny model rehetra ao amin'ny catalogue dia mandray azy; ny GET /v1/models dia milaza capabilities.tools: true ho an'ny id rehetra.

Saha Karazana Famaritana
type string Foana function.
function.name string Ny anarana ampiasain'ny model rehefa mangataka an'io function io. Ilaina.
function.description string Izay ataon'ny function, amin'ny teny tsotra.
function.parameters object Ny arguments ho JSON Schema misy type: "object" eo an-tampony. Jereo ny Keyword an'ny schema etsy ambany.

Ny endpoint tsirairay dia manana fomba fanoratana tool manokana. Alefaso izay an'ilay endpoint antsoinao:

{
  "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

Ny tool_choice dia milaza raha afaka, na tsy maintsy, miantso tool ny model. Vakiana miaraka amin'ny tools ihany izy.

Sanda Famaritana Ampiharin'ny
"auto" Ny model no mamaritra raha hamaly amin'ny soratra na hiantso tool. Io no default. Model rehetra
"required" Miantso tool iray farafahakeliny ny valiny. Model open-weight hosted
{"type": "function", "function": {"name": "get_weather"}} Miantso an'io function io ny valiny. Tsy maintsy iray amin'ny function ao amin'ny tools ny anarana. Ny antso ny function hafa dia tsy ampidirina ao amin'ny valiny. Model open-weight hosted

Ny model Shannon (shannon-*) dia mamaritra isaky ny fangatahana, toy ny amin'ny auto.

Miaraka amin'ny required na function voatondro, vakio ny finish_reason alohan'ny tool_calls. Rehefa tsy mamokatra antso ny model, ny valiny dia valiny soratra miaraka amin'ny finish_reason: "stop".

Dikany /v1/chat/completions /v1/responses /v1/messages
Ny model no mamaritra "auto" "auto" {"type": "auto"}
Miantso tool iray farafahakeliny "required" "required" {"type": "any"}
Miantso function iray voatondro {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Raisina ho an'ny compatibility: tool_choice: "none" sy parallel_tool_calls. Ho an'ny fihodinana tsy misy tool calls, alefaso ny fangatahana tsy misy tools.

Tool calls ao amin'ny valiny

Saha Karazana Famaritana
finish_reason string tool_calls rehefa mitondra antso iray farafahakeliny ny valiny.
message.tool_calls array Iray isaky ny antso. Misy ny saha rehefa nangataka antso ny model ihany.
tool_calls[].id string call_ arahin'ny tarehintsoratra hexadecimal 32. Averina miaraka amin'ny valiny ho tool_call_id.
tool_calls[].type string Foana function.
tool_calls[].function.name string Ny function tokony hotanterahina.
tool_calls[].function.arguments string Ny arguments ho string JSON, "{}" raha tsy misy. Parse-o aloha vao ampiasaina.
message.content string | null null rehefa antso ihany no ao amin'ny valiny. Ny model open-weight hosted dia afaka mamerina soratra miaraka amin'ny antso; ny model Shannon kosa mamerina null.

Ny antso mitovy amin'ny endrika tsirairay. Amin'ny /v1/responses dia item function_call ao amin'ny output, miaraka amin'ny arguments ho string JSON. Amin'ny /v1/messages dia content block tool_use izay object JSON ny input-ny, manomboka amin'ny toolu_ ny id-ny, ary tool_use ny stop_reason.

{
  "finish_reason": "tool_calls",
  "message": {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Paris\"}"
        }
      }
    ]
  }
}

Antso maromaro ao anatin'ny fihodinana iray

Ny valiny iray dia mety mitondra antso maromaro. Ampandehano daholo ary alefaso valiny iray isaky ny antso, samy manana ny tool_call_id-ny, ao amin'ny fangatahana manaraka.

Ny model open-weight hosted dia mamerina indray mandeha ny antso samy hafa: ny antso roa manana anarana sy arguments mitovy dia tonga ho iray.

Tool calls streamed

Miaraka amin'ny stream: true, ny antso dia tonga iray manontolo: ny chunk dia misy ny string arguments feno, ka tsy misy sombintsombiny hampiarahina. Ny index dia manisa ny antso ao amin'ny fihodinana manomboka amin'ny 0.

data: chunk iray, voa-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 Izay tonga
/v1/chat/completions chat.completion.chunk iray isaky ny antso, miaraka amin'ny antso ao amin'ny delta.tool_calls[0]. Ny chunk farany dia manana finish_reason: "tool_calls" sy usage.
/v1/responses Isaky ny antso: response.output_item.added (item function_call misy arguments foana), response.function_call_arguments.delta (ny string manontolo), response.function_call_arguments.done, response.output_item.done.
/v1/messages Isaky ny antso: content_block_start (block tool_use misy input foana), content_block_delta iray izay ny input_json_delta.partial_json no soratra arguments manontolo, content_block_stop. Avy eo ny message_delta dia mitondra stop_reason: "tool_use".

Amin'ny shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ary shannon-coder-1, ny fangatahana streamed mitondra tools dia manome ny soratra valiny ao anaty content delta iray amin'ny faran'ny fihodinana. Fandefasana mivantana

Fandefasana ny valiny

Ny fangatahana faharoa dia mamerina ny resaka ary manampy zavatra roa: ny fihodinan'ny assistant izay nangataka ny antso, sy valiny iray isaky ny antso.

{
  "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\"}"
    }
  ]
}
  • Alefaso indray ny fihodinan'ny assistant araka ny nahazoanao azy, alohan'ny valiny. Ny valiny tsirairay dia ampifanarahina amin'ny antso amin'ny alalan'ny id: tool_call_id amin'ny /v1/chat/completions, call_id amin'ny /v1/responses, tool_use_id amin'ny /v1/messages.
  • Soratra ny valiny. Atao string JSON ny object ho an'ny content (output amin'ny /v1/responses). Amin'ny /v1/messages dia string na lisitry ny text block ny content an'ny block tool_result.
  • Ao amin'ny fihodinan'ny assistant, ny function.arguments dia mijanona ho string JSON, araka ny nahatongavany.
  • Mety hifarana amin'ny valin'ny tool ny resaka. Tsy ilaina hafatra vaovao avy amin'ny mpampiasa: manohy avy amin'ny valiny ny model.
  • Rehefa tsy nahomby ny function-nao, alefaso ho soratra valiny ny tsy fahombiazana. Afaka manambara izany na mangataka antso hafa ny model avy eo.

Keyword an'ny schema

Ny parameters (input_schema amin'ny /v1/messages) dia JSON Schema. Ny fianakavian'i Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) sy ny model open-weight hosted dia mandray azy araka ny nalefanao.

Ny shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ary shannon-coder-1 dia mandray ity ampahany ity, amin'ny endpoint telo rehetra:

Fikarakarana Keyword
Vakiana araka ny nalefa Ny keyword rehetra tsy voatonona ao amin'ny andalana etsy ambany, ohatra type, properties, required, items, enum, description, minimum, maximum, anyOf ary allOf, amin'ny ambaratonga rehetra ao amin'ny schema.
format Vakiana ho an'ny sanda int32, int64, float, double, byte, date, date-time ary enum.
oneOf Vakiana ho anyOf.
Tsy anisan'ny schema raisin'ireto model ireto $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 sy exclusiveMaximum rehefa isa izy ireo; sanda hafa amin'ny format.

Fihetsika sy fetra

  • Ny API dia tsy mametraka isa ambony indrindra ho an'ny tools na ho an'ny fihodinana.
  • Ny body ny fangatahana dia hatramin'ny 32 MiB, ary ny resaka miaraka amin'ny valiny dia tsy maintsy tafiditra ao amin'ny context window an'ny model.
  • Rehefa mitondra tools ny fangatahana, ny shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ary shannon-2-pro dia mampiasa temperature default 0.2. Alefaso ny temperature raha te-hametraka sanda hafa.
  • Ny fihodinana tsirairay dia fangatahana mitokana: mamoaka avy amin'ny balance-nao izy ary ianarana amin'ny flood protection tahaka ny fangatahana hafa. Fetra sy balance

Hadisoana

Ny tool call dia valiny mahazatra miaraka amin'ny status 200. Ireto hadisoana ireto dia momba ny fangatahana mihitsy:

Status Karazana Hafatra Rahoviana
400 invalid_request_error unknown model: <id> Tsy id ao amin'ny lisitra navoaka ny model.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Tsy array ny tools, na diso ny karazana JSON an'ny saha hafa.
413 invalid_request_error Failed to buffer the request body: … Lehibe noho ny 32 MiB ny body ny fangatahana. Ny hadisoana dia mitondra code: "request_too_large".

Ny model no manoratra ny arguments. Hamarino amin'ny schema-nao izy ireo alohan'ny handefasana ny function, tahaka ny fanamarinana input rehetra avy any ivelany.

Ny fanamarinana, ny balance ary ny hadisoan'ny server dia mitovy amin'ny an'ny fangatahana rehetra. Fitantanana hadisoana