Gafee gaa n'ọdịnaya
Oku ọrụ

Oku ọrụ

Kọwaa functions gị na request, model ga-aza site na calls ọ chọrọ ka e mee. Koodu gị na-agba ha ma zighachi results: API na-eweghachi tool calls, ọ naghị agba tool n'onwe ya.

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

Samples dị na peeji a na-eji /v1/chat/completions. Otu loop ahụ na-agba na /v1/responses na /v1/messages; ebe format na-ede ihe n'ụzọ ọzọ, akụkụ ndị dị n'okpuru na-egosi atọ ahụ niile.

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)

Azịza mbụ anaghị aza ajụjụ ahụ. Ọ na-arịọ 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}
  }
}

Mgbe ị zipụrụ result, azịza na-esote bụ azịza nkịtị: message.content nwere text, finish_reason bụkwa stop.

Loop ahụ, nzọụkwụ site na nzọụkwụ

Nzọụkwụ Onye Ihe na-eme
1 Gị Zipụ messages ya na tools, ndepụta functions model nwere ike ịrịọ.
2 Model Azịza ahụ nwere tool_calls na finish_reason: "tool_calls". Call ọ bụla na-akpọ function ma nye arguments ya.
3 Gị Parse arguments nke call ọ bụla ma gbaa function gị.
4 Gị Tinye assistant message na otu tool message maka call ọ bụla na messages, wee zighachi request ahụ na otu tools.
5 Model Model na-aza na text nwere finish_reason: "stop", ma ọ bụ na-arịọ calls ndị ọzọ. N'okwu ahụ laghachi na nzọụkwụ 3.

Otu request bụ otu model turn. API anaghị edebe mkparịta ụka n'etiti requests ma ọ naghị atọ ọnụọgụ gburugburu: koodu gị na-ejide messages ma kpebie mgbe a ga-akwụsị.

Ịkọwa tools

tools bụ array nwere otu entry maka function ọ bụla. Model ọ bụla nke catalogue na-anabata ya; GET /v1/models na-akọ capabilities.tools: true maka id ọ bụla.

Field Ụdị Nkọwa
type string Mgbe niile function.
function.name string Aha model na-eji mgbe ọ na-arịọ function a. Achọrọ.
function.description string Ihe function na-eme, n'asụsụ dị mfe.
function.parameters object Arguments dị ka JSON Schema nwere type: "object" n'elu. Lee Schema keywords n'okpuru.

Endpoint ọ bụla nwere otu o si ede tool. Zipụ nke bụ nke endpoint ị na-akpọ:

{
  "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 na-ekwu ma model nwere ike, ma ọ bụ ga-akpọ tool. A na-agụ ya naanị ya na tools.

Uru Nkọwa Ndị na-etinye ya
"auto" Model na-ekpebi ma ọ ga-aza na text ka ọ ga-akpọ tool. Nke a bụ default. Models niile
"required" Azịza ahụ na-akpọ opekata mpe otu tool. Hosted open-weight models
{"type": "function", "function": {"name": "get_weather"}} Azịza ahụ na-akpọ function a. Aha ahụ ga-abụ otu n'ime functions dị na tools. A na-ahapụ calls maka functions ndị ọzọ n'azịza ahụ. Hosted open-weight models

Shannon models (shannon-*) na-ekpebi n'ime request ọ bụla, dị ka site na auto.

Site na required ma ọ bụ function akpọrọ aha, gụọ finish_reason tupu ị gụọ tool_calls. Mgbe model emepụtaghị call, azịza bụ text nwere finish_reason: "stop".

Nkọwa /v1/chat/completions /v1/responses /v1/messages
Model na-ekpebi "auto" "auto" {"type": "auto"}
Kpọọ opekata mpe otu tool "required" "required" {"type": "any"}
Kpọọ otu function akpọrọ aha {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Anabatara maka ndakọrịta: tool_choice: "none" na parallel_tool_calls. Maka turn na-enweghị tool calls, zipụ request na-enweghị tools.

Tool calls n'azịza

Field Ụdị Nkọwa
finish_reason string tool_calls mgbe azịza ahụ nwere opekata mpe otu call.
message.tool_calls array Otu entry maka call ọ bụla. Field ahụ dị naanị mgbe model rịọrọ call.
tool_calls[].id string call_ sochiri mkpụrụedemede hexadecimal 32. Zighachi ya dị ka tool_call_id na result.
tool_calls[].type string Mgbe niile function.
tool_calls[].function.name string Function a ga-arụ.
tool_calls[].function.arguments string Arguments dị ka JSON string, "{}" mgbe ọ nweghị. Parse ya tupu ojiji.
message.content string | null null mgbe azịza nwere naanị calls. Hosted open-weight models nwere ike ịweghachi text n'akụkụ calls; Shannon models na-eweghachi null.

Otu call ahụ n'format ọ bụla. Na /v1/responses ọ bụ item function_call nke output, nwere arguments dị ka JSON string. Na /v1/messages ọ bụ tool_use content block nke input ya bụ JSON object, id ya na-amalite na toolu_, stop_reason bụkwa 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 dị iche iche n'otu turn

Azịza nwere ike ibu calls dị iche iche. Gbaa ha niile ma zipụ otu result maka call ọ bụla, nke ọ bụla na tool_call_id nke ya, na request na-esote.

Hosted open-weight models na-eweghachi call ọ bụla dị iche otu ugboro: calls abụọ nwere otu aha na otu arguments na-abịa dị ka otu.

Tool calls na stream

Site na stream: true, call na-abịa n'otu akụkụ: chunk nwere string arguments zuru ezu, ya mere enweghị iberibe a ga-ejikọta. index na-agụ calls nke turn site na 0.

data: otu chunk, edozila
{
  "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 Ihe na-abịa
/v1/chat/completions Otu chat.completion.chunk maka call ọ bụla, na call ahụ na delta.tool_calls[0]. Chunk ikpeazụ nwere finish_reason: "tool_calls" na usage.
/v1/responses Maka call ọ bụla: response.output_item.added (item function_call nwere arguments efu), response.function_call_arguments.delta (string dum), response.function_call_arguments.done, response.output_item.done.
/v1/messages Maka call ọ bụla: content_block_start (tool_use block nwere input efu), otu content_block_delta nke input_json_delta.partial_json ya bụ ederede arguments dum, content_block_stop. Mgbe ahụ message_delta nwere stop_reason: "tool_use".

Na shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro na shannon-coder-1, request stream nwere tools na-ebuga ederede azịza ya n'otu content delta na njedebe nke turn. Nzipu ozugbo

Izighachi results

Request nke abụọ na-ekwughachi mkparịta ụka ma na-agbakwunye ihe abụọ: assistant turn rịọrọ calls, na otu result maka call ọ bụla.

{
  "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\"}"
    }
  ]
}
  • Zighachi assistant turn dị ka ị natara ya, tupu results. A na-ejikọta result ọ bụla na call ya site na id: tool_call_id na /v1/chat/completions, call_id na /v1/responses, tool_use_id na /v1/messages.
  • Result bụ text. Mee serialise object ka ọ bụrụ JSON string maka content (output na /v1/responses). Na /v1/messages content nke tool_result block bụ string ma ọ bụ ndepụta text blocks.
  • N'assistant turn, function.arguments ka bụ JSON string, kpọmkwem dị ka o si bịa.
  • Mkparịta ụka nwere ike ịgwụ na tool result. Achọghị user message ọhụrụ: model na-aga n'ihu site na result ahụ.
  • Mgbe function gị daa, zipụ ọdịda ahụ dị ka result text. Model nwere ike ịkọ ya ma ọ bụ rịọ call ọzọ.

Schema keywords

parameters (input_schema na /v1/messages) bụ JSON Schema. Shannon 3 family (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) na hosted open-weight models na-anata ya dị ka ị zipụrụ ya.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro na shannon-coder-1 na-anata subset a, na endpoints atọ ahụ niile:

Ọgwụgwọ Keywords
A na-agụ dị ka e zipụrụ Keyword ọ bụla akpọbeghị aha n'ahịrị dị n'okpuru, dịka type, properties, required, items, enum, description, minimum, maximum, anyOf na allOf, n'ọkwa ọ bụla nke schema.
format A na-agụ maka uru int32, int64, float, double, byte, date, date-time na enum.
oneOf A na-agụ dị ka anyOf.
Abụghị akụkụ nke schema models ndị a na-anata $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 na exclusiveMaximum mgbe ha bụ ọnụọgụ; uru ndị ọzọ nke format.

Omume na limits

  • API anaghị atọ oke ọnụọgụ tools, ọ naghịkwa atọ oke ọnụọgụ gburugburu.
  • Request body nwere ike ịbụ ruo 32 MiB, mkparịta ụka na results ya ga-abakwa n'ime context window nke model.
  • Mgbe request nwere tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite na shannon-2-pro na-eji default temperature nke 0.2. Zipụ temperature iji tọọ uru ọzọ.
  • Gburugburu ọ bụla bụ request nke ya: ọ na-ewepụ site na balance gị ma na-agụ n'ime flood protection dị ka request ọ bụla ọzọ. Limits na balance

Njehie

Tool call bụ azịza nkịtị nwere status 200. Njehie ndị a metụtara request n'onwe ya:

Status Ụdị Ozi Mgbe
400 invalid_request_error unknown model: <id> model abụghị id dị na ndepụta e bipụtara.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools abụghị array, ma ọ bụ field ọzọ nwere JSON type na-ezighi ezi.
413 invalid_request_error Failed to buffer the request body: … Request body buru ibu karịa 32 MiB. Njehie ahụ nwere code: "request_too_large".

Model na-ede arguments. Lelee ha megide schema gị tupu ị gbaa function ahụ, dị ka ị ga-eme maka input ọ bụla si n'èzí.

Authentication, balance na njehie server bụ otu ihe ahụ dị ka maka request ọ bụla. Njikwa njehie