U gudub nuxurka
Wacyigelinta Shaqada

Wacyigelinta Shaqada

Ku sharax functions-kaaga codsiga model-kuna wuxuu ku jawaabayaa wicitaannada uu rabo in la sameeyo. Code-kaagu wuu orodsiiyaa oo natiijooyinka dib buu u diraa: API-gu wuxuu soo celiyaa wicitaannada tool laftiisa tool ma orodsiiyo.

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

Tusaalayaasha bogga waxay isticmaalaan /v1/chat/completions. Isla wareegga ayaa ka shaqeeya /v1/responses iyo /v1/messages; halka qaab uu wax si kale u qoro, qaybaha hoose waxay muujinayaan saddexdaba.

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)

Jawaabta ugu horreysa su'aasha ma jawaabto. Waxay codsataa wicitaan:

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

Ka dib marka aad natiijada dirto, jawaabta xigta waa jawaab caadi ah: message.content wuxuu haystaa qoraalka finish_reason-na waa stop.

Wareegga, tallaabo-tallaabo

Tallaabo Yaa Waxa dhaca
1 Adiga Dir messages iyo tools, liiska functions-ka model-ku codsan karo.
2 Model Jawaabtu waxay sidaa tool_calls iyo finish_reason: "tool_calls". Wicitaan kastaa wuxuu magacaabaa function wuxuuna bixiyaa arguments-kiisa.
3 Adiga Parse-garee arguments wicitaan kasta oo orodsii function-kaaga.
4 Adiga Ku dar fariinta assistant-ka iyo hal fariin tool wicitaan kasta messages, kaddib mar kale dir codsiga isla tools.
5 Model Model-ku wuxuu ku jawaabaa qoraal oo leh finish_reason: "stop", ama wuxuu codsadaa wicitaanno dheeraad ah. Xaaladdaas dib ugu noqo tallaabada 3.

Hal codsi waa hal wareeg model. API-gu wada-hadal u dhexeeya codsiyada ma hayo, tiro wareegyo ahna ma dejiyo: code-kaagu wuxuu hayaa messages wuxuuna go'aamiyaa goorta la joojinayo.

Qeexidda tools

tools waa array leh hal gelin function kasta. Model kasta oo kataloogga ahi wuu aqbalaa; GET /v1/models wuxuu id kasta u sheegaa capabilities.tools: true.

Field Nooc Sharaxaad
type string Had iyo jeer function.
function.name string Magaca model-ku isticmaalo marka uu function-kan codsado. Loo baahan yahay.
function.description string Waxa function-ku sameeyo, luqad cad.
function.parameters object Arguments-ka sida JSON Schema oo type: "object" ugu sarreeyo. Eeg Erayada schema hoose.

Endpoint kastaa wuxuu leeyahay qoraal u gaar ah oo tool ah. Dir kan endpoint-ka aad wacayso ka tirsan:

{
  "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 wuxuu sheegaa in model-ku wici karo, ama waajib tahay inuu wacdo, tool. Waxaa la akhriyaa tools la socda oo keliya.

Qiime Sharaxaad Waxay dabaqaan
"auto" Model-ku wuxuu go'aansadaa inuu ku jawaabo qoraal ama inuu wacdo tool. Kani waa default-ka. Dhammaan model-yada
"required" Jawaabtu waxay wacdaa ugu yaraan hal tool. Model-yada open-weight ee la martigeliyo
{"type": "function", "function": {"name": "get_weather"}} Jawaabtu waxay wacdaa function-kan. Magacu waa inuu ahaadaa mid ka mid ah functions-ka tools. Wicitaannada functions-ka kale jawaabta laga tagaa. Model-yada open-weight ee la martigeliyo

Model-yada Shannon (shannon-*) codsi kasta ayay go'aansadaan, sida auto.

Marka required ama function la magacaabay, akhri finish_reason ka hor inta aadan akhrin tool_calls. Marka model-ku wicitaan soo saarin, jawaabtu waa jawaab qoraal ah oo leh finish_reason: "stop".

Macne /v1/chat/completions /v1/responses /v1/messages
Model-ku wuu go'aansadaa "auto" "auto" {"type": "auto"}
Wac ugu yaraan hal tool "required" "required" {"type": "any"}
Wac hal function oo la magacaabay {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

La aqbalay u waafaqsanaan: tool_choice: "none" iyo parallel_tool_calls. Wareeg aan lahayn wicitaannada tool, codsiga dir tools la'aantiis.

Wicitaannada tool jawaabta ku jira

Field Nooc Sharaxaad
finish_reason string tool_calls marka jawaabtu sidato ugu yaraan hal wicitaan.
message.tool_calls array Hal gelin wicitaan kasta. Field-ku wuxuu jiraa marka model-ku wicitaan codsaday oo keliya.
tool_calls[].id string call_ oo ay raacayso 32 xaraf hexadecimal ah. Dib ugu dir sida tool_call_id natiijada la socota.
tool_calls[].type string Had iyo jeer function.
tool_calls[].function.name string Function-ka la orodsiinayo.
tool_calls[].function.arguments string Arguments-ka sida string JSON ah, "{}" marka midna jirin. Parse-garee ka hor isticmaalka.
message.content string | null null marka jawaabtu wicitaanno keliya haysato. Model-yada open-weight ee la martigeliyo way soo celin karaan qoraal wicitaannada agtooda; model-yada Shannon waxay soo celiyaan null.

Isla wicitaanka qaab kasta. /v1/responses waa shay function_call ah oo ka mid ah output, oo leh arguments sida string JSON ah. /v1/messages waa content block tool_use oo input kiisu yahay shay JSON ah, id kiisu ku bilaabmo toolu_, stop_reason-na yahay 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\"}"
        }
      }
    ]
  }
}

Dhowr wicitaan hal wareeg

Jawaab waxay sidi kartaa dhowr wicitaan. Dhammaantood orodsii oo hal natiijo wicitaan kasta dir, mid kastaa wuxuu leeyahay tool_call_id u gaar ah, codsiga xiga.

Model-yada open-weight ee la martigeliyo wicitaan kasta oo kala duwan hal mar ayay soo celiyaan: laba wicitaan oo isla magac iyo isla arguments leh waxay u yimaadaan sida mid.

Wicitaannada tool ee stream-ka

Marka stream: true, wicitaan wuxuu u yimaadaa hal gabal: chunk-gu wuxuu haystaa string-ka arguments oo dhammaystiran, sidaas darteed qaybo la isku xiro ma jiraan. index wuxuu tiriyaa wicitaannada wareegga laga bilaabo 0.

data: hal chunk, qaabaysan
{
  "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 Waxa yimaada
/v1/chat/completions Hal chat.completion.chunk wicitaan kasta, wicitaanka oo ku jira delta.tool_calls[0]. Chunk-ga ugu dambeeya wuxuu leeyahay finish_reason: "tool_calls" iyo usage.
/v1/responses Wicitaan kasta: response.output_item.added (shay function_call oo leh arguments madhan), response.function_call_arguments.delta (string-ka oo dhan), response.function_call_arguments.done, response.output_item.done.
/v1/messages Wicitaan kasta: content_block_start (block tool_use oo leh input madhan), hal content_block_delta oo input_json_delta.partial_json yahay qoraalka arguments-ka oo dhan, content_block_stop. message_delta kaddib wuxuu sidaa stop_reason: "tool_use".

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro iyo shannon-coder-1, codsi stream ah oo sida tools wuxuu qoraalka jawaabtiisa ku gaarsiiyaa hal delta content dhammaadka wareegga. Streaming

Dib u dirista natiijooyinka

Codsiga labaad wuxuu ku celiyaa wada-hadalka wuxuuna ku daraa laba shay: wareegga assistant-ka ee wicitaannada codsaday, iyo hal natiijo wicitaan kasta.

{
  "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\"}"
    }
  ]
}
  • Wareegga assistant-ka dib ugu dir sida aad u heshay, ka hor natiijooyinka. Natiij kasta waxaa wicitaankeeda lagu waafajiyaa id: tool_call_id /v1/chat/completions, call_id /v1/responses, tool_use_id /v1/messages.
  • Natiijadu waa qoraal. U serialize-garee shay string JSON ah content (output /v1/responses). /v1/messages content ee block-ga tool_result waa string ama liis blocks qoraal ah.
  • Wareegga assistant-ka, function.arguments wuxuu ahaanayaa string JSON ah, sida uu u yimid.
  • Wada-hadalku wuxuu ku dhammaan karaa natiijo tool. Fariin isticmaale oo cusub looma baahna: model-ku wuxuu ka sii wadaa natiijada.
  • Marka function-kaagu fashilmo, fashilka u dir sida qoraalka natiijada. Model-ku kaddib wuu sheegi karaa ama wuxuu codsan karaa wicitaan kale.

Erayada schema

parameters (input_schema /v1/messages) waa JSON Schema. Qoyska Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) iyo model-yada open-weight ee la martigeliyo way helaan sida aad u dirto.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro iyo shannon-coder-1 waxay helaan qayb-yar kan, saddexda endpoint:

Maareyn Erayo muhiim ah
Waxaa la akhriyaa sida loo diray Eray kasta oo aan lagu magacaabin safafka hoose, tusaale ahaan type, properties, required, items, enum, description, minimum, maximum, anyOf iyo allOf, heer kasta oo schema-ha ah.
format Waxaa la akhriyaa qiimayaasha int32, int64, float, double, byte, date, date-time iyo enum.
oneOf Waxaa loo akhriyaa sida anyOf.
Qayb ma aha schema-ha model-yadani helaan $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 iyo exclusiveMaximum marka ay yihiin tirooyin; qiimayaasha kale ee format.

Dabeecad iyo xadad

  • API-gu ma dejiyo tirada ugu badan ee tools ama tirada ugu badan ee wareegyada.
  • Jidhka codsigu wuxuu noqon karaa ilaa 32 MiB, wada-hadalka iyo natiijooyinkiisuna waa inay ku soo galaan context window-ka model-ka.
  • Marka codsi sido tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite iyo shannon-2-pro waxay isticmaalaan temperature default ah oo ah 0.2. Dir temperature si aad u dejiso qiime kale.
  • Wareeg kastaa waa codsi u gaar ah: wuxuu ka qaadaa haraaggaaga wuxuuna ka tirsan yahay flood protection sida codsi kasta oo kale. Xadad iyo haraag

Khaladaad

Wicitaanka tool waa jawaab caadi ah oo leh xaalad 200. Khaladaadkan waxay khusaan codsiga laftiisa:

Xaalad Nooc Fariin Goorta
400 invalid_request_error unknown model: <id> model ma aha id ka mid ah liiska la daabacay.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools ma aha array, ama field kale wuxuu leeyahay nooc JSON qaldan.
413 invalid_request_error Failed to buffer the request body: … Jidhka codsigu wuu ka weyn yahay 32 MiB. Khaladku wuxuu sidaa code: "request_too_large".

Model-ku wuxuu qoraa arguments-ka. Ku hubi schema-gaaga ka hor inta aadan orodsiin function-ka, sida aad u hubin lahayd input kasta oo dibadda ka yimaada.

Xaqiijinta, haraagga iyo khaladaadka server-ku waa isku mid codsi kasta. Khaladaadka Maareynta