Ruka hadi kwenye maudhui
Uitoaji wa kazi

Uitoaji wa kazi

Eleza functions zako kwenye ombi na model hujibu na wito inaotaka ufanywe. Code yako inaziendesha na kutuma matokeo nyuma: API hurudisha wito wa tools na haiendeshi tool yenyewe.

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

Mifano kwenye ukurasa huu inatumia /v1/chat/completions. Mzunguko ule ule unaendeshwa kwenye /v1/responses na /v1/messages; mahali umbizo linapoandika kitu tofauti, sehemu zilizo hapa chini zinaonyesha zote tatu.

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)

Jibu la kwanza halijibu swali. Linaomba wito:

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

Baada ya kutuma matokeo, jibu linalofuata ni jibu la kawaida: message.content ina maandishi na finish_reason ni stop.

Mzunguko, hatua kwa hatua

Hatua Nani Nini hutokea
1 Wewe Tuma messages pamoja na tools, orodha ya functions ambazo model inaweza kuomba.
2 Model Jibu hubeba tool_calls na finish_reason: "tool_calls". Kila wito unataja function na kutoa arguments zake.
3 Wewe Changanua (parse) arguments za kila wito na uendeshe function yako.
4 Wewe Ongeza ujumbe wa assistant na ujumbe mmoja wa tool kwa kila wito kwenye messages, kisha tuma ombi tena na tools zile zile.
5 Model Model hujibu kwa maandishi na finish_reason: "stop", au huomba wito zaidi. Katika hali hiyo rudi kwenye hatua ya 3.

Ombi moja ni zamu moja ya model. API haihifadhi mazungumzo kati ya maombi na haiweki idadi ya raundi: code yako inashikilia messages na kuamua wakati wa kusimama.

Kufafanua tools

tools ni array yenye entry moja kwa kila function. Kila model ya katalogi inaikubali; GET /v1/models huripoti capabilities.tools: true kwa kila id.

Field Aina Maelezo
type string Daima function.
function.name string Jina ambalo model hutumia inapoomba function hii. Inahitajika.
function.description string Function inafanya nini, kwa lugha rahisi.
function.parameters object Arguments kama JSON Schema yenye type: "object" juu. Tazama Keywords za schema hapa chini.

Kila endpoint ina namna yake ya kuandika tool. Tuma ile inayohusiana na endpoint unayoita:

{
  "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 inasema kama model inaweza, au lazima, iite tool. Husomwa pamoja na tools tu.

Thamani Maelezo Inatumiwa na
"auto" Model inaamua kama ijibu kwa maandishi au iite tool. Hii ndiyo chaguo-msingi. Model zote
"required" Jibu linaita angalau tool moja. Model za open-weight zinazopangishwa
{"type": "function", "function": {"name": "get_weather"}} Jibu linaita function hii. Jina lazima liwe mojawapo ya functions kwenye tools. Wito wa functions nyingine huachwa nje ya jibu. Model za open-weight zinazopangishwa

Model za Shannon (shannon-*) huamua kwenye kila ombi, kama kwa auto.

Kwa required au function iliyotajwa, soma finish_reason kabla ya kusoma tool_calls. Model isipotoa wito, jibu ni la maandishi lenye finish_reason: "stop".

Maana /v1/chat/completions /v1/responses /v1/messages
Model inaamua "auto" "auto" {"type": "auto"}
Ita angalau tool moja "required" "required" {"type": "any"}
Ita function moja iliyotajwa {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Zinakubaliwa kwa ulinganifu: tool_choice: "none" na parallel_tool_calls. Kwa zamu isiyo na wito wa tools, tuma ombi bila tools.

Wito wa tools kwenye jibu

Field Aina Maelezo
finish_reason string tool_calls wakati jibu lina angalau wito mmoja.
message.tool_calls array Entry moja kwa kila wito. Field ipo tu wakati model iliomba wito.
tool_calls[].id string call_ ikifuatiwa na herufi 32 za hexadecimal. Irudishe kama tool_call_id pamoja na matokeo.
tool_calls[].type string Daima function.
tool_calls[].function.name string Function ya kuendesha.
tool_calls[].function.arguments string Arguments kama JSON string, "{}" wakati hakuna. Ichanganue (parse) kabla ya kutumia.
message.content string | null null wakati jibu lina wito pekee. Model za open-weight zinazopangishwa zinaweza kurudisha maandishi kando ya wito; model za Shannon hurudisha null.

Wito ule ule katika kila umbizo. Kwenye /v1/responses ni item ya function_call ya output, na arguments kama JSON string. Kwenye /v1/messages ni content block ya tool_use ambayo input yake ni kitu cha JSON, id yake huanza na toolu_, na stop_reason ni 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\"}"
        }
      }
    ]
  }
}

Wito kadhaa katika zamu moja

Jibu linaweza kubeba wito kadhaa. Endesha kila mmoja na utume matokeo moja kwa kila wito, kila moja na tool_call_id yake, kwenye ombi linalofuata.

Model za open-weight zinazopangishwa hurudisha kila wito tofauti mara moja: wito mbili zenye jina lile lile na arguments zile zile hufika kama mmoja.

Wito wa tools kwenye stream

Kwa stream: true, wito hufika kwa kipande kimoja: chunk ina string kamili ya arguments, kwa hiyo hakuna vipande vya kuunganisha. index huhesabu wito wa zamu kuanzia 0.

data: chunk moja, iliyopangwa 
{
  "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 Kinachofika
/v1/chat/completions chat.completion.chunk moja kwa kila wito, na wito ukiwa kwenye delta.tool_calls[0]. Chunk ya mwisho ina finish_reason: "tool_calls" na usage.
/v1/responses Kwa kila wito: response.output_item.added (item ya function_call yenye arguments tupu), response.function_call_arguments.delta (string nzima), response.function_call_arguments.done, response.output_item.done.
/v1/messages Kwa kila wito: content_block_start (block ya tool_use yenye input tupu), content_block_delta moja ambayo input_json_delta.partial_json yake ni maandishi yote ya arguments, content_block_stop. Kisha message_delta hubeba stop_reason: "tool_use".

Kwenye shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro na shannon-coder-1, ombi la stream linalobeba tools hutoa maandishi ya jibu katika delta moja ya content mwishoni mwa zamu. Kutiririsha

Kutuma matokeo nyuma

Ombi la pili hurudia mazungumzo na kuongeza vitu viwili: zamu ya assistant iliyoomba wito, na matokeo moja kwa kila wito.

{
  "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\"}"
    }
  ]
}
  • Rudisha zamu ya assistant kama ulivyoipokea, kabla ya matokeo. Kila matokeo hulinganishwa na wito wake kwa id: tool_call_id kwenye /v1/chat/completions, call_id kwenye /v1/responses, tool_use_id kwenye /v1/messages.
  • Matokeo ni maandishi. Geuza kitu kuwa JSON string kwa content (output kwenye /v1/responses). Kwenye /v1/messages content ya block ya tool_result ni string au orodha ya blocks za maandishi.
  • Kwenye zamu ya assistant, function.arguments hubaki JSON string, kama ilivyofika hasa.
  • Mazungumzo yanaweza kuisha na matokeo ya tool. Ujumbe mpya wa user hauhitajiki: model huendelea kutoka kwenye matokeo.
  • Function yako ikishindwa, tuma kushindwa huko kama maandishi ya matokeo. Model kisha inaweza kuliripoti au kuomba wito mwingine.

Keywords za schema

parameters (input_schema kwenye /v1/messages) ni JSON Schema. Familia ya Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) na model za open-weight zinazopangishwa huipokea kama unavyoituma.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro na shannon-coder-1 hupokea sehemu hii ndogo, kwenye endpoint zote tatu:

Namna inavyoshughulikiwa Keywords
Husomwa kama ilivyotumwa Kila keyword isiyotajwa kwenye safu zilizo hapa chini, kwa mfano type, properties, required, items, enum, description, minimum, maximum, anyOf na allOf, katika kila ngazi ya schema.
format Husomwa kwa thamani int32, int64, float, double, byte, date, date-time na enum.
oneOf Husomwa kama anyOf.
Si sehemu ya schema ambayo model hizi hupokea $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 zikiwa namba; thamani nyingine za format.

Tabia na mipaka

  • API haiweki idadi ya juu ya tools wala idadi ya juu ya raundi.
  • Mwili wa ombi unaweza kuwa hadi 32 MiB, na mazungumzo pamoja na matokeo yake lazima yatoshee kwenye dirisha la muktadha la model.
  • Ombi likibeba tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite na shannon-2-pro hutumia temperature chaguo-msingi ya 0.2. Tuma temperature kuweka thamani nyingine.
  • Kila raundi ni ombi lake lenyewe: hutumia salio lako na huhesabiwa kwenye flood protection kama ombi lingine lolote. Mipaka na salio

Makosa

Wito wa tool ni jibu la kawaida lenye hali 200. Makosa haya yanahusu ombi lenyewe:

Hali Aina Ujumbe Lini
400 invalid_request_error unknown model: <id> model si id ya orodha iliyochapishwa.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools si array, au field nyingine ina aina isiyo sahihi ya JSON.
413 invalid_request_error Failed to buffer the request body: … Mwili wa ombi ni mkubwa kuliko 32 MiB. Kosa hubeba code: "request_too_large".

Model huandika arguments. Zikague dhidi ya schema yako kabla ya kuendesha function, kama ungekagua input yoyote ya nje.

Makosa ya uthibitishaji, salio na seva ni yale yale kama kwa kila ombi. Ushughulikiaji wa Makosa