Dumphani kupita ku zomwe zili
Kuyitana mafunkseni

Kuyitana mafunkseni

Fotokozani ma function anu mu pempho ndipo model imayankha ndi ma call omwe ikufuna kuti achitidwe. Code yanu imawayendetsa ndikutumiza zotsatira: API imabweza ma call a tool ndipo siiyendetsa tool yokha.

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

Zitsanzo za patsamba lino zimagwiritsa ntchito /v1/chat/completions. Loop yomweyo imayenda pa /v1/responses ndi /v1/messages; mtundu ukalemba chinthu mosiyana, magawo apansipa amaonetsa onse atatu.

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)

Yankho loyamba silimayankha funso. Limapempha 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}
  }
}

Mukatumiza zotsatira, yankho lotsatira ndi yankho lanthawi zonse: message.content ili ndi text ndipo finish_reason ndi stop.

Loop, sitepe ndi sitepe

Sitepe Ndani Zomwe zimachitika
1 Inu Tumizani messages pamodzi ndi tools, mndandanda wa ma function omwe model ingapemphe.
2 Model Yankho limanyamula tool_calls ndi finish_reason: "tool_calls". Call iliyonse imatchula function ndikupereka ma argument ake.
3 Inu Santhulani arguments ya call iliyonse ndipo yendetsani function yanu.
4 Inu Onjezani message ya assistant ndi message imodzi ya tool pa call iliyonse ku messages, kenako tumizaninso pempho ndi tools yomweyo.
5 Model Model imayankha ndi text ndi finish_reason: "stop", kapena imapempha ma call ena. Pamenepo bwererani ku sitepe 3.

Pempho limodzi ndi turn imodzi ya model. API siisunga zokambirana pakati pa ma pempho ndipo siikhazikitsa chiwerengero cha ma round: code yanu imasunga messages ndipo imasankha nthawi yoyimira.

Kufotokoza ma tool

tools ndi array yokhala ndi entry imodzi pa function iliyonse. Model iliyonse ya catalogue imailandira; GET /v1/models imanena capabilities.tools: true pa id iliyonse.

Field Mtundu Kufotokozera
type string Nthawi zonse function.
function.name string Dzina lomwe model imagwiritsa ntchito ikapempha function iyi. Lofunika.
function.description string Zomwe function imachita, m'mawu osavuta.
function.parameters object Ma argument ngati JSON Schema yokhala ndi type: "object" pamwamba. Onani Ma keyword a schema pansipa.

Endpoint iliyonse ili ndi kalembedwe kake ka tool. Tumizani yomwe ikugwirizana ndi endpoint yomwe mukuyitana:

{
  "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 imanena ngati model ingathe, kapena iyenera, kuyitana tool. Imawerengedwa pamodzi ndi tools yokha.

Mtengo Kufotokozera Imagwira ntchito pa
"auto" Model imasankha ngati iyankhe ndi text kapena iyitane tool. Ichi ndi default. Ma model onse
"required" Yankho limayitana tool imodzi osachepera. Hosted open-weight model
{"type": "function", "function": {"name": "get_weather"}} Yankho limayitana function iyi. Dzinalo liyenera kukhala limodzi la ma function a mu tools. Ma call a ma function ena samaikidwa mu yankho. Hosted open-weight model

Ma model a Shannon (shannon-*) amasankha pa pempho lililonse, monga ndi auto.

Ndi required kapena function yotchulidwa, werengani finish_reason musanawerenge tool_calls. Model ikapanda call, yankho limakhala text ndi finish_reason: "stop".

Tanthauzo /v1/chat/completions /v1/responses /v1/messages
Model imasankha "auto" "auto" {"type": "auto"}
Yitanani tool imodzi osachepera "required" "required" {"type": "any"}
Yitanani function imodzi yotchulidwa {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Zimalandiridwa pofuna kugwirizana: tool_choice: "none" ndi parallel_tool_calls. Pa turn yopanda ma call a tool, tumizani pempho popanda tools.

Ma call a tool mu yankho

Field Mtundu Kufotokozera
finish_reason string tool_calls pamene yankho lili ndi call imodzi osachepera.
message.tool_calls array Entry imodzi pa call iliyonse. Field imakhalapo pokhapokha model itapempha call.
tool_calls[].id string call_ yotsatiridwa ndi zilembo 32 za hexadecimal. Ibwezeni ngati tool_call_id pamodzi ndi zotsatira.
tool_calls[].type string Nthawi zonse function.
tool_calls[].function.name string Function yoyenera kuyendetsedwa.
tool_calls[].function.arguments string Ma argument ngati JSON string, "{}" pamene palibe. Isanthuleni musanaigwiritse ntchito.
message.content string | null null pamene yankho lili ndi ma call okha. Hosted open-weight model zimatha kubweza text pambali pa ma call; ma model a Shannon amabweza null.

Call yomweyo mu mtundu uliwonse. Pa /v1/responses ndi item ya function_call ya output, ndi arguments ngati JSON string. Pa /v1/messages ndi content block ya tool_use yomwe input yake ndi JSON object, id yake imayamba ndi toolu_, ndipo stop_reason ndi 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\"}"
        }
      }
    ]
  }
}

Ma call angapo mu turn imodzi

Yankho likhoza kunyamula ma call angapo. Yendetsani onse ndikutumiza zotsatira imodzi pa call iliyonse, iliyonse ndi tool_call_id yake, mu pempho lotsatira.

Hosted open-weight model zimabweza call iliyonse yosiyana kamodzi: ma call awiri okhala ndi dzina lomwelo ndi ma argument omwewo amafika ngati amodzi.

Ma call a tool mu stream

Ndi stream: true, call imafika yonse pamodzi: chunk ili ndi string yonse ya arguments, choncho palibe zigawo zolumikiza. index imawerenga ma call a turn kuyambira pa 0.

data: chunk imodzi, yokonzedwa
{
  "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 Zomwe zimafika
/v1/chat/completions chat.completion.chunk imodzi pa call iliyonse, ndi call mu delta.tool_calls[0]. Chunk yomaliza ili ndi finish_reason: "tool_calls" ndi usage.
/v1/responses Pa call iliyonse: response.output_item.added (item ya function_call yokhala ndi arguments yopanda kanthu), response.function_call_arguments.delta (string yonse), response.function_call_arguments.done, response.output_item.done.
/v1/messages Pa call iliyonse: content_block_start (block ya tool_use yokhala ndi input yopanda kanthu), content_block_delta imodzi yomwe input_json_delta.partial_json yake ndi text yonse ya ma argument, content_block_stop. Kenako message_delta imanyamula stop_reason: "tool_use".

Pa shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ndi shannon-coder-1, pempho la stream lokhala ndi tools limapereka text ya yankho mu content delta imodzi kumapeto kwa turn. Kutsitsa nthawi yeniyeni

Kutumiza zotsatira

Pempho lachiwiri limabwereza zokambirana ndikuwonjezera zinthu ziwiri: turn ya assistant yomwe idapempha ma call, ndi zotsatira imodzi pa call iliyonse.

{
  "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\"}"
    }
  ]
}
  • Bwezerani turn ya assistant monga mudailandirira, zotsatira zisanafike. Zotsatira iliyonse imafananizidwa ndi call yake ndi id: tool_call_id pa /v1/chat/completions, call_id pa /v1/responses, tool_use_id pa /v1/messages.
  • Zotsatira ndi text. Sinthani object kukhala JSON string ya content (output pa /v1/responses). Pa /v1/messages, content ya block ya tool_result ndi string kapena mndandanda wa ma text block.
  • Mu turn ya assistant, function.arguments imakhalabe JSON string, monga idafikira.
  • Zokambirana zikhoza kutha ndi zotsatira za tool. Palibe message yatsopano ya user yofunika: model imapitiriza kuchokera ku zotsatira.
  • Function yanu ikalephera, tumizani cholakwikacho ngati text ya zotsatira. Model ikhoza kuchinena kapena kupempha call ina.

Ma keyword a schema

parameters (input_schema pa /v1/messages) ndi JSON Schema. Banja la Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ndi hosted open-weight model zimaipeza monga mwaitumizira.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ndi shannon-coder-1 zimalandira gawo ili, pa ma endpoint onse atatu:

Momwe imagwiritsidwira Ma keyword
Imawerengedwa monga yatumizidwa Keyword iliyonse yosatchulidwa mu mizere ili pansipa, mwachitsanzo type, properties, required, items, enum, description, minimum, maximum, anyOf ndi allOf, pa mlingo uliwonse wa schema.
format Imawerengedwa pa mitengo int32, int64, float, double, byte, date, date-time ndi enum.
oneOf Imawerengedwa ngati anyOf.
Siili gawo la schema yomwe ma model awa amalandira $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 ndi exclusiveMaximum zikakhala manambala; mitengo ina ya format.

Khalidwe ndi malire

  • API siikhazikitsa chiwerengero chokwanira cha ma tool kapena cha ma round.
  • Body ya pempho ikhoza kufika 32 MiB, ndipo zokambirana ndi zotsatira zake ziyenera kukwana mu context window ya model.
  • Pempho likakhala ndi tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ndi shannon-2-pro zimagwiritsa ntchito temperature ya default ya 0.2. Tumizani temperature kuti mukhazikitse mtengo wina.
  • Round iliyonse ndi pempho lake: imatenga pa balance yanu ndipo imawerengedwa pa flood protection monga pempho lina lililonse. Malire ndi balance

Zolakwika

Call ya tool ndi yankho labwinobwino lokhala ndi status 200. Zolakwika izi zimakhudza pempho lokha:

Status Mtundu Message Liti
400 invalid_request_error unknown model: <id> model si id ya mndandanda wofalitsidwa.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools si array, kapena field ina ili ndi JSON type yolakwika.
413 invalid_request_error Failed to buffer the request body: … Body ya pempho ndi yayikulu kuposa 32 MiB. Cholakwika chimanyamula code: "request_too_large".

Model imalemba ma argument. Ayang'aneni motsutsana ndi schema yanu musanayendetse function, monga mungayang'anire input iliyonse yakunja.

Zolakwika za authentication, balance ndi server ndi zofanana ndi za pempho lililonse. Zolakwika