Tsallake zuwa abun ciki
Kiran Aiki

Kiran Aiki

Ku bayyana functions ɗinku a cikin request kuma model yana amsawa da kiran da yake so a yi. Code ɗinku yana gudanar da su kuma yana mayar da sakamakon: API yana mayar da kiran tool kuma ba ya gudanar da tool da kansa.

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

Samfuran da ke wannan shafin suna amfani da /v1/chat/completions. Loop iri ɗaya yana gudana a /v1/responses da /v1/messages; inda tsari ke rubuta wani abu daban, sassan da ke ƙasa suna nuna dukkan uku.

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)

Amsar farko ba ta amsa tambayar ba. Tana neman kira:

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

Bayan kun aika sakamakon, amsa ta gaba amsa ce ta al'ada: message.content yana ɗauke da rubutun kuma finish_reason shi ne stop.

Loop, mataki bayan mataki

Mataki Wane Abin da ke faruwa
1 Ku Ku aika messages tare da tools, jerin functions da model zai iya nema.
2 Model Amsar tana ɗauke da tool_calls da finish_reason: "tool_calls". Kowane kira yana ambaton function kuma yana ba da arguments ɗinsa.
3 Ku Ku parse arguments na kowane kira kuma ku gudanar da function ɗinku.
4 Ku Ku ƙara saƙon assistant da saƙon tool ɗaya ga kowane kira zuwa messages, sannan ku sake aika request da tools iri ɗaya.
5 Model Model yana amsawa da rubutu tare da finish_reason: "stop", ko ya nemi ƙarin kira. A wannan yanayin ku koma mataki na 3.

Request ɗaya turn ɗaya ne na model. API ba ya riƙe tattaunawa tsakanin requests kuma ba ya sanya adadin zagaye: code ɗinku ne ke riƙe messages kuma yake yanke shawarar lokacin tsayawa.

Bayyana tools

tools array ne mai shigarwa ɗaya ga kowane function. Kowane model na jerin yana karɓarsa; GET /v1/models yana bayyana capabilities.tools: true ga kowane id.

Field Nau'i Bayani
type string Koyaushe function.
function.name string Sunan da model ke amfani da shi lokacin da yake neman wannan function. Wajibi.
function.description string Abin da function ke yi, da harshe mai sauƙi.
function.parameters object Arguments a matsayin JSON Schema mai type: "object" a sama. Duba Schema keywords a ƙasa.

Kowane endpoint yana da nasa rubutun tool. Ku aika wanda ya dace da endpoint da kuke kira:

{
  "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 yana faɗin ko model zai iya, ko dole ne, ya kira tool. Ana karanta shi tare da tools kaɗai.

Ƙima Bayani Wanda ke aiwatarwa
"auto" Model ne ke yanke shawarar amsawa da rubutu ko kiran tool. Wannan shi ne na asali. Duk models
"required" Amsar tana kiran tool aƙalla ɗaya. Hosted open-weight models
{"type": "function", "function": {"name": "get_weather"}} Amsar tana kiran wannan function. Dole sunan ya zama ɗaya daga functions a cikin tools. Ana bar kiran wasu functions daga cikin amsar. Hosted open-weight models

Models na Shannon (shannon-*) suna yanke shawara a kowace request, kamar da auto.

Da required ko function mai suna, ku karanta finish_reason kafin ku karanta tool_calls. Idan model bai samar da kira ba, amsar rubutu ce mai finish_reason: "stop".

Ma'ana /v1/chat/completions /v1/responses /v1/messages
Model ne ke yanke shawara "auto" "auto" {"type": "auto"}
Kiran tool aƙalla ɗaya "required" "required" {"type": "any"}
Kiran function ɗaya mai suna {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Ana karɓa don jituwa: tool_choice: "none" da parallel_tool_calls. Don turn ba tare da kiran tool ba, ku aika request ba tare da tools ba.

Kiran tool a cikin amsa

Field Nau'i Bayani
finish_reason string tool_calls idan amsar tana ɗauke da kira aƙalla ɗaya.
message.tool_calls array Shigarwa ɗaya ga kowane kira. Field ɗin yana nan ne kawai idan model ya nemi kira.
tool_calls[].id string call_ da ke biye da haruffan hexadecimal 32. Ku mayar da shi a matsayin tool_call_id tare da sakamakon.
tool_calls[].type string Koyaushe function.
tool_calls[].function.name string Function da za a gudanar.
tool_calls[].function.arguments string Arguments a matsayin JSON string, "{}" idan babu. Ku parse shi kafin amfani.
message.content string | null null idan amsar tana ɗauke da kira kaɗai. Hosted open-weight models na iya mayar da rubutu tare da kiran; models na Shannon suna mayar da null.

Kira iri ɗaya a kowane tsari. A /v1/responses item ne na function_call na output, tare da arguments a matsayin JSON string. A /v1/messages content block ne na tool_use wanda input ɗinsa JSON object ne, id ɗinsa yana farawa da toolu_, kuma stop_reason shi ne 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\"}"
        }
      }
    ]
  }
}

Kira da yawa a turn ɗaya

Amsa na iya ɗaukar kira da yawa. Ku gudanar da kowannensu kuma ku aika sakamako ɗaya ga kowane kira, kowanne da tool_call_id nasa, a request na gaba.

Hosted open-weight models suna mayar da kowane kira na musamman sau ɗaya: kira biyu masu suna iri ɗaya da arguments iri ɗaya suna zuwa a matsayin ɗaya.

Kiran tool da aka yi streaming

Da stream: true, kira yana zuwa a guda ɗaya: chunk yana ɗauke da cikakken string na arguments, don haka babu gutsuttsura da za a haɗa. index yana ƙirga kiran turn daga 0.

data: chunk ɗaya, an tsara shi 
{
  "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 Abin da ke zuwa
/v1/chat/completions chat.completion.chunk ɗaya ga kowane kira, tare da kiran a delta.tool_calls[0]. Chunk na ƙarshe yana da finish_reason: "tool_calls" da usage.
/v1/responses Ga kowane kira: response.output_item.added (item na function_call mai arguments mara komai), response.function_call_arguments.delta (dukan string ɗin), response.function_call_arguments.done, response.output_item.done.
/v1/messages Ga kowane kira: content_block_start (block na tool_use mai input mara komai), content_block_delta ɗaya wanda input_json_delta.partial_json ɗinsa shi ne dukan rubutun arguments, content_block_stop. Sannan message_delta yana ɗauke da stop_reason: "tool_use".

A shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro da shannon-coder-1, request da aka yi streaming mai ɗauke da tools yana kawo rubutun amsarsa a delta ɗaya na content a ƙarshen turn. Yawo

Mayar da sakamako

Request na biyu yana maimaita tattaunawar kuma yana ƙara abubuwa biyu: turn na assistant da ya nemi kiran, da sakamako ɗaya ga kowane kira.

{
  "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\"}"
    }
  ]
}
  • Ku mayar da turn na assistant yadda kuka karɓe shi, kafin sakamakon. Ana haɗa kowane sakamako da kiransa ta id: tool_call_id a /v1/chat/completions, call_id a /v1/responses, tool_use_id a /v1/messages.
  • Sakamako rubutu ne. Ku mayar da object zuwa JSON string don content (output a /v1/responses). A /v1/messages content na block na tool_result string ne ko jerin text blocks.
  • A turn na assistant, function.arguments yana nan JSON string, daidai yadda ya iso.
  • Tattaunawar na iya ƙarewa da sakamakon tool. Ba a buƙatar sabon saƙon mai amfani: model yana ci gaba daga sakamakon.
  • Idan function ɗinku ya gaza, ku aika gazawar a matsayin rubutun sakamako. Model sai ya iya bayar da rahotonta ko ya nemi wani kira.

Schema keywords

parameters (input_schema a /v1/messages) JSON Schema ne. Iyalin Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) da hosted open-weight models suna karɓar sa yadda kuka aika.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro da shannon-coder-1 suna karɓar wannan ɓangare, a dukkan endpoints uku:

Yadda ake sarrafa Keywords
Ana karantawa yadda aka aika Kowane keyword da ba a ambace shi a layukan da ke ƙasa ba, misali type, properties, required, items, enum, description, minimum, maximum, anyOf da allOf, a kowane mataki na schema.
format Ana karantawa ga ƙimomin int32, int64, float, double, byte, date, date-time da enum.
oneOf Ana karantawa a matsayin anyOf.
Ba sashen schema ba ne da waɗannan models ke karɓa $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 da exclusiveMaximum idan lambobi ne; sauran ƙimomin format.

Hali da iyakoki

  • API ba ya sanya mafi yawan adadin tools kuma ba ya sanya mafi yawan adadin zagaye.
  • Jikin request na iya kaiwa 32 MiB, kuma tattaunawar tare da sakamakonta dole ta shiga cikin context window na model.
  • Idan request yana ɗauke da tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite da shannon-2-pro suna amfani da temperature na asali na 0.2. Ku aika temperature don saita wata ƙima.
  • Kowane zagaye request ne na kansa: yana ɗaukar daga balance ɗinku kuma ana ƙirga shi a flood protection kamar kowace request. Iyakoki da balance

Kurakurai

Kiran tool amsa ce ta al'ada mai matsayi 200. Waɗannan kurakurai suna shafar request da kansa:

Matsayi Nau'i Saƙo Lokaci
400 invalid_request_error unknown model: <id> model ba id ba ne na jerin da aka wallafa.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools ba array ba ne, ko kuma wani field yana da nau'in JSON mara kyau.
413 invalid_request_error Failed to buffer the request body: … Jikin request ya fi 32 MiB girma. Kuskuren yana ɗauke da code: "request_too_large".

Model ne ke rubuta arguments. Ku duba su da schema ɗinku kafin ku gudanar da function, kamar yadda za ku duba kowane input daga waje.

Kurakuran tabbatarwa, balance da server iri ɗaya ne da na kowace request. Kuskuren Gudanarwa