Fò lọ sí àkóónú
Ipe iṣẹ

Ipe iṣẹ

Ṣàpèjúwe àwọn function rẹ nínú ìbéèrè, model náà yóò sì dáhùn pẹ̀lú àwọn ìpè tó fẹ́ kí a ṣe. Code rẹ ń ṣe wọ́n, ó sì ń fi àwọn abajade ránṣẹ́ padà: API ń dá àwọn ìpè tool padà, kì í sì í ṣe tool fúnra rẹ̀.

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

Àwọn àpẹẹrẹ ojú-ìwé yìí ń lo /v1/chat/completions. Loop kan náà ń ṣiṣẹ́ lórí /v1/responses àti /v1/messages; níbi tí ọ̀nà kan bá kọ nǹkan lọ́nà míràn, àwọn apá ìsàlẹ̀ fi mẹ́tẹ̀ẹ̀ta hàn.

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)

Èsì àkọ́kọ́ kò dáhùn ìbéèrè náà. Ó ń béèrè ìpè kan:

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

Lẹ́yìn tí o bá fi abajade ránṣẹ́, èsì tó kàn jẹ́ ìdáhùn àtọwọ́dọ́wọ́: message.content gbé ọ̀rọ̀ náà mú, finish_reason sì jẹ́ stop.

Loop náà, ìgbésẹ̀ lẹ́yìn ìgbésẹ̀

Ìgbésẹ̀ Ta ni Ohun tó ń ṣẹlẹ̀
1 Ìwọ Fi messages ránṣẹ́ pẹ̀lú tools, àtòjọ àwọn function tí model lè béèrè.
2 Model Èsì náà gbé tool_calls àti finish_reason: "tool_calls". Ìpè kọ̀ọ̀kan dárúkọ function ó sì fún un ní àwọn argument rẹ̀.
3 Ìwọ Parse arguments ti ìpè kọ̀ọ̀kan kí o sì ṣe function rẹ.
4 Ìwọ Fi ìfiránṣẹ́ assistant àti ìfiránṣẹ́ tool kan fún ìpè kọ̀ọ̀kan kún messages, lẹ́yìn náà fi ìbéèrè náà ránṣẹ́ lẹ́ẹ̀kan sí i pẹ̀lú tools kan náà.
5 Model Model dáhùn ní ọ̀rọ̀ pẹ̀lú finish_reason: "stop", tàbí ó béèrè àwọn ìpè síwájú sí i. Ní ọ̀ràn yẹn, padà sí ìgbésẹ̀ 3.

Ìbéèrè kan jẹ́ ìyípo model kan. API kì í pa ìjíròrò mọ́ láàrín àwọn ìbéèrè, kò sì ṣètò iye yípo: code rẹ ni ó ń di messages mú tó sì ń pinnu ìgbà tí yóò dúró.

Ṣíṣàlàyé àwọn tool

tools jẹ́ array pẹ̀lú ìkọ̀sílẹ̀ kan fún function kọ̀ọ̀kan. Gbogbo model inú catalogue ń gba á; GET /v1/models ń ròyìn capabilities.tools: true fún gbogbo id.

Field Irú Àpèjúwe
type string Nígbà gbogbo function.
function.name string Orúkọ tí model ń lò nígbà tó bá béèrè function yìí. Dandan.
function.description string Ohun tí function náà ń ṣe, ní èdè lásán.
function.parameters object Àwọn argument bí JSON Schema pẹ̀lú type: "object" ní òkè. Wo Àwọn keyword schema ní ìsàlẹ̀.

Endpoint kọ̀ọ̀kan ní ọ̀nà tirẹ̀ láti kọ tool. Fi èyí tó jẹ́ ti endpoint tí o ń pè ránṣẹ́:

{
  "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 sọ bóyá model lè, tàbí gbọdọ̀, pe tool. A ń kà á pẹ̀lú tools nìkan.

Iye Àpèjúwe Ó ń ṣiṣẹ́ lórí
"auto" Model ni ó ń pinnu bóyá yóò dáhùn ní ọ̀rọ̀ tàbí yóò pe tool. Èyí ni àìyípadà. Gbogbo model
"required" Èsì náà ń pe tool kan tó kéré jù. Àwọn model open-weight tí a gbàlejò
{"type": "function", "function": {"name": "get_weather"}} Èsì náà ń pe function yìí. Orúkọ náà gbọdọ̀ jẹ́ ọ̀kan nínú àwọn function inú tools. A fi àwọn ìpè sí àwọn function mìíràn sílẹ̀ kúrò nínú èsì. Àwọn model open-weight tí a gbàlejò

Àwọn model Shannon (shannon-*) ń pinnu ní ìbéèrè kọ̀ọ̀kan, bí pẹ̀lú auto.

Pẹ̀lú required tàbí function tí a dárúkọ, ka finish_reason kí o tó ka tool_calls. Nígbà tí model kò bá mú ìpè kankan jáde, èsì náà jẹ́ ìdáhùn ọ̀rọ̀ pẹ̀lú finish_reason: "stop".

Ìtumọ̀ /v1/chat/completions /v1/responses /v1/messages
Model ni ó ń pinnu "auto" "auto" {"type": "auto"}
Pe tool kan tó kéré jù "required" "required" {"type": "any"}
Pe function kan tí a dárúkọ {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

A gbà fún ìbáramu: tool_choice: "none" àti parallel_tool_calls. Fún ìyípo láìsí ìpè tool, fi ìbéèrè ránṣẹ́ láìsí tools.

Àwọn ìpè tool nínú èsì

Field Irú Àpèjúwe
finish_reason string tool_calls nígbà tí èsì bá gbé ìpè kan tó kéré jù.
message.tool_calls array Ìkọ̀sílẹ̀ kan fún ìpè kọ̀ọ̀kan. Field náà wà nígbà tí model bá béèrè ìpè nìkan.
tool_calls[].id string call_ tí àwọn ọ̀rọ̀ hexadecimal 32 tẹ̀lé. Fi ránṣẹ́ padà bí tool_call_id pẹ̀lú abajade.
tool_calls[].type string Nígbà gbogbo function.
tool_calls[].function.name string Function tí a ó ṣe.
tool_calls[].function.arguments string Àwọn argument bí string JSON, "{}" nígbà tí kò bá sí. Parse rẹ̀ kí o tó lò ó.
message.content string | null null nígbà tí èsì bá ní àwọn ìpè nìkan. Àwọn model open-weight tí a gbàlejò lè dá ọ̀rọ̀ padà lẹ́gbẹ̀ẹ́ àwọn ìpè; àwọn model Shannon ń dá null padà.

Ìpè kan náà ní ọ̀nà kọ̀ọ̀kan. Lórí /v1/responses ó jẹ́ ohun function_call ti output, pẹ̀lú arguments bí string JSON. Lórí /v1/messages ó jẹ́ block àkóónú tool_use tí input rẹ̀ jẹ́ object JSON, id rẹ̀ bẹ̀rẹ̀ pẹ̀lú toolu_, stop_reason sì jẹ́ 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\"}"
        }
      }
    ]
  }
}

Ọ̀pọ̀ ìpè nínú ìyípo kan

Èsì kan lè gbé ọ̀pọ̀ ìpè. Ṣe gbogbo wọn kí o sì fi abajade kan ránṣẹ́ fún ìpè kọ̀ọ̀kan, ọ̀kọ̀ọ̀kan pẹ̀lú tool_call_id tirẹ̀, nínú ìbéèrè tó kàn.

Àwọn model open-weight tí a gbàlejò ń dá ìpè kọ̀ọ̀kan tó yàtọ̀ padà lẹ́ẹ̀kan: ìpè méjì pẹ̀lú orúkọ kan náà àti àwọn argument kan náà ń dé bí ọ̀kan.

Àwọn ìpè tool nínú stream

Pẹ̀lú stream: true, ìpè dé ní ẹyọ kan: chunk gbé string arguments pípé, nítorí náà kò sí àwọn ègé láti so pọ̀. index ń ka àwọn ìpè ìyípo láti 0.

data: chunk kan, tí a ṣe ní ọ̀nà tó rọrùn láti kà 
{
  "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 Ohun tó ń dé
/v1/chat/completions chat.completion.chunk kan fún ìpè kọ̀ọ̀kan, pẹ̀lú ìpè náà nínú delta.tool_calls[0]. Chunk tó gbẹ̀yìn ní finish_reason: "tool_calls" àti usage.
/v1/responses Fún ìpè kọ̀ọ̀kan: response.output_item.added (ohun function_call pẹ̀lú arguments òfo), response.function_call_arguments.delta (gbogbo string náà), response.function_call_arguments.done, response.output_item.done.
/v1/messages Fún ìpè kọ̀ọ̀kan: content_block_start (block tool_use pẹ̀lú input òfo), content_block_delta kan tí input_json_delta.partial_json rẹ̀ jẹ́ gbogbo ọ̀rọ̀ àwọn argument, content_block_stop. message_delta lẹ́yìn náà gbé stop_reason: "tool_use".

Lórí shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro àti shannon-coder-1, ìbéèrè streaming tó gbé tools ń fi ọ̀rọ̀ ìdáhùn rẹ̀ jáde nínú delta content kan ní òpin ìyípo. Sisanwọle

Fífi àwọn abajade ránṣẹ́ padà

Ìbéèrè kejì tún ìjíròrò náà sọ, ó sì fi nǹkan méjì kún un: ìyípo assistant tó béèrè àwọn ìpè, àti abajade kan fún ìpè kọ̀ọ̀kan.

{
  "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\"}"
    }
  ]
}
  • Fi ìyípo assistant ránṣẹ́ padà bí o ṣe gbà á, ṣáájú àwọn abajade. A so abajade kọ̀ọ̀kan mọ́ ìpè rẹ̀ nípasẹ̀ id: tool_call_id lórí /v1/chat/completions, call_id lórí /v1/responses, tool_use_id lórí /v1/messages.
  • Abajade jẹ́ ọ̀rọ̀. Serialise object sí string JSON fún content (output lórí /v1/responses). Lórí /v1/messages, content ti block tool_result jẹ́ string tàbí àtòjọ àwọn block ọ̀rọ̀.
  • Nínú ìyípo assistant, function.arguments ṣì jẹ́ string JSON, gẹ́gẹ́ bí ó ṣe dé.
  • Ìjíròrò lè parí pẹ̀lú abajade tool. A kò nílò ìfiránṣẹ́ user tuntun: model ń tẹ̀síwájú láti abajade náà.
  • Nígbà tí function rẹ bá kùnà, fi ìkùnà náà ránṣẹ́ bí ọ̀rọ̀ abajade. Model lè ròyìn rẹ̀ lẹ́yìn náà tàbí béèrè ìpè mìíràn.

Àwọn keyword schema

parameters (input_schema lórí /v1/messages) jẹ́ JSON Schema. Ìdílé Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) àti àwọn model open-weight tí a gbàlejò ń gbà á bí o ṣe fi ránṣẹ́.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro àti shannon-coder-1 ń gba ìpín yìí, lórí gbogbo endpoint mẹ́tẹ̀ẹ̀ta:

Ìtọ́jú Àwọn keyword
A ń kà á bí a ṣe fi ránṣẹ́ Gbogbo keyword tí a kò dárúkọ nínú àwọn ìlà ìsàlẹ̀, fún àpẹẹrẹ type, properties, required, items, enum, description, minimum, maximum, anyOf àti allOf, ní gbogbo ìpele schema.
format A ń kà á fún àwọn iye int32, int64, float, double, byte, date, date-time àti enum.
oneOf A ń kà á bí anyOf.
Kì í ṣe apá schema tí àwọn model wọ̀nyí ń gbà $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 àti exclusiveMaximum nígbà tí wọ́n bá jẹ́ nọ́ńbà; àwọn iye format mìíràn.

Ìhùwà àti àwọn ààlà

  • API kò ṣètò iye tool tó pọ̀ jù àti iye yípo tó pọ̀ jù.
  • Body ìbéèrè lè tó 32 MiB, ìjíròrò pẹ̀lú àwọn abajade rẹ̀ sì gbọdọ̀ wọ inú context window ti model.
  • Nígbà tí ìbéèrè bá gbé tools, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite àti shannon-2-pro ń lo temperature àìyípadà ti 0.2. Fi temperature ránṣẹ́ láti ṣètò iye mìíràn.
  • Yípo kọ̀ọ̀kan jẹ́ ìbéèrè tirẹ̀: ó ń yọ láti balance rẹ, ó sì ń ṣe kún ààbò flood bí ìbéèrè mìíràn. Àwọn ààlà àti balance

Àwọn àṣìṣe

Ìpè tool jẹ́ èsì àtọwọ́dọ́wọ́ pẹ̀lú status 200. Àwọn àṣìṣe wọ̀nyí kàn ìbéèrè fúnra rẹ̀:

Ipò Irú Ìfiránṣẹ́ Nígbà wo
400 invalid_request_error unknown model: <id> model kì í ṣe id ti àtòjọ tí a tẹ̀ jáde.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools kì í ṣe array, tàbí field mìíràn ní irú JSON tí kò tọ̀.
413 invalid_request_error Failed to buffer the request body: … Body ìbéèrè tóbi ju 32 MiB. Àṣìṣe náà gbé code: "request_too_large".

Model ni ó ń kọ àwọn argument. Ṣàyẹ̀wò wọn lòdì sí schema rẹ kí o tó ṣe function náà, bí o ṣe máa ṣàyẹ̀wò input èyíkéyìí láti ẹ̀yìn òde.

Àwọn àṣìṣe authentication, balance àti server jẹ́ bákan náà fún gbogbo ìbéèrè. Mimu Aṣiṣe