Simira kuzvirimo
Kudanwa kwemabasa

Kudanwa kwemabasa

Tsanangura functions dzako mu-request uye model inopindura ne-calls yaunoda dzitwe. Code yako inodzimhanyisa ndokutumira mhedzisiro kudzoka: API inodzosa tool calls uye haimhanyise tool pachayo.

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

Ma-sample ari papeji rino anoshandisa /v1/chat/completions. Loop imwechete inomhanya pa-/v1/responses ne-/v1/messages; kwakanyorwa zvakasiyana ne-format, zvikamu zviri pazasi zvinoratidza ese matatu.

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)

Mhinduro yekutanga haipindure mubvunzo. Inokumbira 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}
  }
}

Mushure mekutumira mhedzisiro, mhinduro inotevera i-answer yakajairika: message.content ine text uye finish_reason i-stop.

Loop, danho nedanho

Danho Ani Zvinoitika
1 Iwe Tumira messages pamwe chete ne-tools, list ye-functions dzinogona kukumbirwa ne-model.
2 Model Mhinduro inotakura tool_calls ne-finish_reason: "tool_calls". Call imwe neimwe inotumidza function uye inopa arguments dzayo.
3 Iwe Parse arguments ye-call imwe neimwe uye umhanyise function yako.
4 Iwe Wedzera assistant message ne-tool message imwe pa-call imwe mu-messages, wobva watumira request zvakare ne-tools dzimwechete.
5 Model Model inopindura ne-text ine finish_reason: "stop", kana kukumbira calls dzimwe. Mune iyoyo nyaya dzokera ku-danho 3.

Request imwe i-model turn imwe. API haichengeti hurukuro pakati pe-requests uye haiise huwandu hwe-rounds: code yako inochengeta messages uye inosarudza kuti inomira rinhi.

Kutsanangura tools

tools i-array ine entry imwe pa-function imwe. Model imwe neimwe yemu-catalogue inoigamuchira; GET /v1/models inoratidza capabilities.tools: true ye-id imwe neimwe.

Field Mhando Tsananguro
type string Inogara iri function.
function.name string Zita rinoshandiswa ne-model kana ichikumbira function iyi. Rinodiwa.
function.description string Zvinoitwa ne-function, mumashoko akajeka.
function.parameters object Arguments se-JSON Schema ine type: "object" kumusoro. Tarisa Schema keywords pazasi.

Endpoint imwe neimwe ine manyorerwo ayo e-tool. Tumira iyo yeendpoint yaunodanidzira:

{
  "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 inoti model inogona, kana inofanira, kudanidzira tool. Inoverengwa pamwe chete ne-tools chete.

Value Tsananguro Inoshandiswa ne
"auto" Model inosarudza kupindura nge-text kana kudanidzira tool. Iyi ndiyo default. Ma-model ese
"required" Mhinduro inodanidzira tool imwe zvishoma. Hosted open-weight models
{"type": "function", "function": {"name": "get_weather"}} Mhinduro inodanidzira function iyi. Zita rinofanira kuva rimwe re-functions dziri mu-tools. Calls kune dzimwe functions dzinosiiwa mumhinduro. Hosted open-weight models

Shannon models (shannon-*) dzinosarudza pa-request imwe neimwe, sezvakaita ne-auto.

Ne-required kana function yakatumidzwa, verenga finish_reason usati waverenga tool_calls. Kana model isingagadzire call, mhinduro i-text answer ine finish_reason: "stop".

Zvinorehwa /v1/chat/completions /v1/responses /v1/messages
Model inosarudza "auto" "auto" {"type": "auto"}
Danidzira tool imwe zvishoma "required" "required" {"type": "any"}
Danidzira function imwe yakatumidzwa {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Dzinogamuchirwa kuti zvienderane: tool_choice: "none" ne-parallel_tool_calls. Pa-turn isina tool calls, tumira request isina tools.

Tool calls mumhinduro

Field Mhando Tsananguro
finish_reason string tool_calls kana mhinduro ine call imwe zvishoma.
message.tool_calls array Entry imwe pa-call imwe. Field iripo chete kana model yakukumbira call.
tool_calls[].id string call_ inoteverwa ne-hexadecimal characters 32. Idzorere se-tool_call_id pamwe chete nemhedzisiro.
tool_calls[].type string Inogara iri function.
tool_calls[].function.name string Function yekumhanyisa.
tool_calls[].function.arguments string Arguments se-JSON string, "{}" kana dzisipo. Dzi-parse usati wadzishandisa.
message.content string | null null kana mhinduro ine calls bedzi. Hosted open-weight models dzinogona kudzosa text padivi pe-calls; Shannon models dzinodzosa null.

Call imwechete mu-format imwe neimwe. Pa-/v1/responses i-function_call item ye-output, ine arguments se-JSON string. Pa-/v1/messages i-tool_use content block ine input iri JSON object, id yayo inotanga ne-toolu_, uye stop_reason i-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\"}"
        }
      }
    ]
  }
}

Calls dzakawanda mu-turn imwe

Mhinduro inogona kutakura calls dzakawanda. Dzimhanyise dzese uye utumire mhedzisiro imwe pa-call imwe, imwe neimwe ine tool_call_id yayo, mu-request inotevera.

Hosted open-weight models dzinodzosa call imwe neimwe yakasiyana kamwe: calls mbiri dzine zita rimwechete uye arguments dzimwechete dzinouya sechimwe.

Streamed tool calls

Ne-stream: true, call inouya yakazara: chunk ine arguments string yakazara, saka hapana zvimedu zvekubatanidza. index inoverenga calls dze-turn kubva pa-0.

data: chunk imwe, yakarongwa
{
  "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 Zvinouya
/v1/chat/completions chat.completion.chunk imwe pa-call imwe, ine call mu-delta.tool_calls[0]. Chunk yekupedzisira ine finish_reason: "tool_calls" ne-usage.
/v1/responses Pa-call imwe: response.output_item.added (function_call item ine arguments isina chinhu), response.function_call_arguments.delta (string yose), response.function_call_arguments.done, response.output_item.done.
/v1/messages Pa-call imwe: content_block_start (tool_use block ine input isina chinhu), content_block_delta imwe ine input_json_delta.partial_json iri arguments text yose, content_block_stop. message_delta inobva yatakura stop_reason: "tool_use".

Pa-shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ne-shannon-coder-1, request ye-stream inotakura tools inounza text yemhinduro mu-content delta imwe pakupera kwe-turn. Kuyerera

Kutumira mhedzisiro kudzoka

Request yechipiri inodzokorora hurukuro uye inowedzera zvinhu zviviri: assistant turn yakakumbira calls, nemhedzisiro imwe pa-call imwe.

{
  "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\"}"
    }
  ]
}
  • Dzorera assistant turn sezvawainge wakaiwana, pamberi pemhedzisiro. Mhedzisiro imwe neimwe inowirirana ne-call yayo nge-id: tool_call_id pa-/v1/chat/completions, call_id pa-/v1/responses, tool_use_id pa-/v1/messages.
  • Mhedzisiro i-text. Shandura object kuita JSON string ye-content (output pa-/v1/responses). Pa-/v1/messages content ye-tool_result block i-string kana list ye-text blocks.
  • Mu-assistant turn, function.arguments inoramba iri JSON string, sezvayakasvika.
  • Hurukuro inogona kupera ne-tool result. Hapana user message itsva inodiwa: model inoenderera kubva pamhedzisiro.
  • Kana function yako ikundikana, tumira kundikana se-result text. Model inobva yaigona kuiudza kana kukumbira call imwe.

Schema keywords

parameters (input_schema pa-/v1/messages) i-JSON Schema. Mhuri ye-Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ne-hosted open-weight models dzinoigamuchira sezvaunotumira.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ne-shannon-coder-1 dzinogamuchira subset iyi, pa-endpoints dzese nhatu:

Kubatwa Keywords
Inoverengwa sezvatumirwa Keyword imwe neimwe isina kutumidzwa mumarow ari pazasi, semuenzaniso type, properties, required, items, enum, description, minimum, maximum, anyOf ne-allOf, pa-level imwe neimwe ye-schema.
format Inoverengwa pa-values int32, int64, float, double, byte, date, date-time ne-enum.
oneOf Inoverengwa se-anyOf.
Haisi chikamu che-schema inogamuchirwa nema-model aya $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 ne-exclusiveMaximum kana ari manhamba; mamwe values e-format.

Hunhu ne-limits

  • API haiise maximum ye-tools uye haiise maximum ye-rounds.
  • Request body inogona kusvika ku-32 MiB, uye hurukuro pamwe nemhedzisiro yayo inofanira kukwana mu-context window ye-model.
  • Kana request ichitakura tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ne-shannon-2-pro dzinoshandisa default temperature ye-0.2. Tumira temperature kuti uise value imwe.
  • Round imwe neimwe i-request yayo pachayo: inotora kubva mu-balance yako uye inoverengwa mu-flood protection semamwe ma-request ese. Limits ne-balance

Errors

Tool call i-reply yakajairika ine status 200. Ma-error aya anoreva request pachayo:

Status Mhando Message Rinhi
400 invalid_request_error unknown model: <id> model haisi id yemu-published list.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools haisi array, kana imwe field ine JSON type isiriyo.
413 invalid_request_error Failed to buffer the request body: … Request body yakakura kupfuura 32 MiB. Error inotakura code: "request_too_large".

Model ndiyo inonyora arguments. Dzitarise nechishandiso che-schema yako usati wamhanyisa function, sezvaungatarisa input yega yega yekunze.

Authentication, balance ne-server errors zvakafanana nepa-request imwe neimwe. Zvikanganiso