Eqa uye okuqukethwe
Ukubiza umsebenzi

Ukubiza umsebenzi

Chaza imisebenzi yakho esicelweni bese i-model iphendula ngokubiza efuna kwenziwe. Ikhodi yakho iyawenza bese ithumela imiphumela: i-API ibuyisela ukubiza amathuluzi futhi ayisebenzisi ithuluzi ngokwayo.

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

Amasampula kuleli khasi asebenzisa i-/v1/chat/completions. Isiyingi esifanayo sisebenza ku-/v1/responses na-/v1/messages; lapho ifomethi ibhala into ngokuhlukile, izigaba ezingezansi zibonisa zonke ezintathu.

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)

Impendulo yokuqala ayiphenduli umbuzo. Icela ukubiza:

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

Ngemva kokuthumela umphumela, impendulo elandelayo iyimpendulo evamile: i-message.content iphatha umbhalo futhi i-finish_reason ithi stop.

Isiyingi, isinyathelo ngesinyathelo

Isinyathelo Ubani Kwenzekani
1 Wena Thumela i-messages ndawonye ne-tools, uhlu lwemisebenzi i-model engayicela.
2 I-model Impendulo iphatha i-tool_calls ne-finish_reason: "tool_calls". Ukubiza ngakunye kuqamba umsebenzi futhi kunikeza izimpikiswano zawo.
3 Wena Hlaziya i-arguments yokubiza ngakunye bese usebenzisa umsebenzi wakho.
4 Wena Engeza umlayezo we-assistant nomlayezo owodwa we-tool ekubizeni ngakunye ku-messages, bese uthumela isicelo futhi nge-tools efanayo.
5 I-model I-model iphendula ngombhalo nge-finish_reason: "stop", noma icela ukubiza okwengeziwe. Kulokho buyela esinyathelweni 3.

Isicelo esisodwa siyisinyathelo esisodwa se-model. I-API ayigcini ingxoxo phakathi kwezicelo futhi ayibeki inani lemijikelezo: ikhodi yakho iphatha i-messages futhi inquma ukuthi iyeke nini.

Ukuchaza amathuluzi

I-tools iyuhlu olunokufakwayo okukodwa ngomsebenzi ngamunye. Wonke ama-model enkathalogi ayayamukela; i-GET /v1/models ibika i-capabilities.tools: true ku-id ngayinye.

I-field Uhlobo Incazelo
type string Njalo function.
function.name string Igama i-model eliyisebenzisayo uma icela lo msebenzi. Liyadingeka.
function.description string Lokho umsebenzi okwenzayo, ngolimi olulula.
function.parameters object Izimpikiswano njenge-JSON Schema ene-type: "object" phezulu. Bheka Amagama angukhiye e-schema ngezansi.

I-endpoint ngayinye inendlela yayo yokubhala ithuluzi. Thumela leyo engeye-endpoint oyibizayo:

{
  "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

I-tool_choice ithi i-model ingabiza, noma kufanele ibize, ithuluzi. Ifundwa kuphela ndawonye ne-tools.

Inani Incazelo Kusebenza ku-
"auto" I-model inquma ukuthi iphendule ngombhalo yini noma ibize ithuluzi. Lokhu kuyisimiso. Wonke ama-model
"required" Impendulo ibiza ithuluzi okungenani elilodwa. Ama-model e-open-weight ahlinzekiwe
{"type": "function", "function": {"name": "get_weather"}} Impendulo ibiza lo msebenzi. Igama kufanele libe elinye lemisebenzi ku-tools. Ukubiza eminye imisebenzi kushiywa empendulweni. Ama-model e-open-weight ahlinzekiwe

Ama-model e-Shannon (shannon-*) anquma kuso sonke isicelo, njenge-auto.

Nge-required noma umsebenzi onegama, funda i-finish_reason ngaphambi kokufunda i-tool_calls. Uma i-model ingakhiqizi ukubiza, impendulo iyimpendulo yombhalo ene-finish_reason: "stop".

Incazelo /v1/chat/completions /v1/responses /v1/messages
I-model iyanquma "auto" "auto" {"type": "auto"}
Biza okungenani ithuluzi elilodwa "required" "required" {"type": "any"}
Biza umsebenzi owodwa onegama {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Kuyamukelwa ukuze kuhambisane: i-tool_choice: "none" ne-parallel_tool_calls. Esikhathini esingenakho ukubiza amathuluzi, thumela isicelo ngaphandle kwe-tools.

Ukubiza amathuluzi empendulweni

I-field Uhlobo Incazelo
finish_reason string tool_calls uma impendulo iphethe ukubiza okungenani okukodwa.
message.tool_calls array Okufakiwe okukodwa ekubizeni ngakunye. I-field ikhona kuphela uma i-model icele ukubiza.
tool_calls[].id string I-call_ elandelwa yizinhlamvu ze-hexadecimal ezingu-32. Yithumele futhi njenge-tool_call_id nomphumela.
tool_calls[].type string Njalo function.
tool_calls[].function.name string Umsebenzi okufanele usetshenziswe.
tool_calls[].function.arguments string Izimpikiswano njenge-string ye-JSON, "{}" uma zingekho. Yihlaziye ngaphambi kokuyisebenzisa.
message.content string | null null uma impendulo iphethe ukubiza kuphela. Ama-model e-open-weight ahlinzekiwe angabuyisela umbhalo eceleni kokubiza; ama-model e-Shannon abuyisela null.

Ukubiza okufanayo ngefomethi ngayinye. Ku-/v1/responses kuyinto ye-function_call ye-output, nge-arguments njenge-string ye-JSON. Ku-/v1/messages kuyi-block yokuqukethwe ye-tool_use okuthi i-input yayo yinto ye-JSON, i-id yayo iqala nge-toolu_, futhi i-stop_reason ithi 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\"}"
        }
      }
    ]
  }
}

Ukubiza okuningana esinyathelweni esisodwa

Impendulo ingaphatha ukubiza okuningana. Sebenzisa wonke bese uthumela umphumela owodwa ekubizeni ngakunye, ngamunye ne-tool_call_id yawo, esicelweni esilandelayo.

Ama-model e-open-weight ahlinzekiwe abuyisela ukubiza ngakunye okuhlukile kanye: ukubiza okubili okunegama elifanayo nezimpikiswano ezifanayo kufika njengokukodwa.

Ukubiza amathuluzi okusakazwayo

Nge-stream: true, ukubiza kufika kuyisiqephu esisodwa: i-chunk iphatha i-string ephelele ye-arguments, ngakho akukho izingcezu zokuhlanganisa. I-index ibala ukubiza kwesinyathelo kusukela ku-0.

data: i-chunk eyodwa, ehlelwe kahle
{
  "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
    }
  ]
}
I-endpoint Okufikayo
/v1/chat/completions I-chat.completion.chunk eyodwa ekubizeni ngakunye, nokubiza ku-delta.tool_calls[0]. I-chunk yokugcina inayo i-finish_reason: "tool_calls" ne-usage.
/v1/responses Ekubizeni ngakunye: i-response.output_item.added (into ye-function_call ene-arguments engenalutho), i-response.function_call_arguments.delta (i-string yonke), i-response.function_call_arguments.done, i-response.output_item.done.
/v1/messages Ekubizeni ngakunye: i-content_block_start (i-block ye-tool_use ene-input engenalutho), i-content_block_delta eyodwa okuthi i-input_json_delta.partial_json yayo umbhalo wonke wezimpikiswano, i-content_block_stop. I-message_delta bese iphatha i-stop_reason: "tool_use".

Ku-shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ne-shannon-coder-1, isicelo esisakazwayo esiphethe i-tools sethula umbhalo wempendulo yaso ku-delta eyodwa ye-content ekupheleni kwesinyathelo. Ukusakaza

Ukuthumela imiphumela emuva

Isicelo sesibili siphinda ingxoxo bese sengeza izinto ezimbili: isinyathelo se-assistant eyacela ukubiza, nomphumela owodwa ekubizeni ngakunye.

{
  "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\"}"
    }
  ]
}
  • Thumela isinyathelo se-assistant njengoba uyitholile, ngaphambi kwemiphumela. Umphumela ngamunye uhambisana nokubiza kwawo nge-id: i-tool_call_id ku-/v1/chat/completions, i-call_id ku-/v1/responses, i-tool_use_id ku-/v1/messages.
  • Umphumela ungumbhalo. Shintsha into ibe yi-string ye-JSON ye-content (i-output ku-/v1/responses). Ku-/v1/messages i-content ye-block ye-tool_result iyi-string noma uhlu lwama-block ombhalo.
  • Esinyathelweni se-assistant, i-function.arguments ihlala iyi-string ye-JSON, njengoba yafika ngempela.
  • Ingxoxo ingaphela ngomphumela wethuluzi. Akudingeki umlayezo omusha womsebenzisi: i-model iqhubeka kusukela emphumelweni.
  • Uma umsebenzi wakho uhluleka, thumela ukwehluleka njengombhalo womphumela. I-model ingakubika noma icele ukubiza okunye.

Amagama angukhiye e-schema

I-parameters (i-input_schema ku-/v1/messages) iyi-JSON Schema. Umndeni we-Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) nama-model e-open-weight ahlinzekiwe ayitholela njengoba uyithumela.

I-shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ne-shannon-coder-1 zitholela le ngxenye, kuwo wonke ama-endpoint amathathu:

Ukwelashwa Amagama angukhiye
Ifundwa njengoba ithunyelwe Igama ngalinye elingukhiye elingaqanjwanga emigqeni engezansi, isibonelo type, properties, required, items, enum, description, minimum, maximum, anyOf ne-allOf, kuwo wonke amazinga e-schema.
format Ifundelwa amanani int32, int64, float, double, byte, date, date-time ne-enum.
oneOf Ifundwa njenge-anyOf.
Akuyona ingxenye ye-schema le ma-model ayitholayo $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 ne-exclusiveMaximum uma ziyizinombolo;amanye amanani e-format.

Ukuziphatha nemikhawulo

  • I-API ayibeki inani eliphezulu lamathuluzi futhi ayibeki inani eliphezulu lemijikelezo.
  • Umzimba wesicelo ungafika ku-32 MiB, futhi ingxoxo nemiphumela yayo kufanele ingene ewindini lomongo le-model.
  • Uma isicelo siphethe i-tools, i-shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ne-shannon-2-pro zisebenzisa i-temperature ezenzakalelayo engu-0.2. Thumela i-temperature ukuze usethe elinye inani.
  • Umjikelezo ngamunye uyisicelo ngokwawo: usebenzisa i-balance yakho futhi ubalwa ku-flood protection njengesinye isicelo. Imikhawulo ne-balance

Amaphutha

Ukubiza ithuluzi kuyimpendulo evamile enesimo 200. La maphutha ahlobene nesicelo ngokwaso:

Isimo Uhlobo Umlayezo Nini
400 invalid_request_error unknown model: <id> I-model akuyona i-id eyohlwini olushicilelwe.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … I-tools akuyona uhlu, noma enye i-field inohlobo olungalungile lwe-JSON.
413 invalid_request_error Failed to buffer the request body: … Umzimba wesicelo mkhulu kuno-32 MiB. Iphutha liphatha code: "request_too_large".

I-model ibhala izimpikiswano. Zihlole ngokuqhathanisa ne-schema yakho ngaphambi kokusebenzisa umsebenzi, njengoba ubungahlola noma yikuphi okufakwayo kwangaphandle.

Amaphutha okuqinisekisa, e-balance ne-server afana nalawo ezicelweni zonke. Ukuphathwa kwamaphutha