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) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const 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"],
},
},
}];
// Your code: ask a weather service here.
function getWeather({ city, unit = "celsius" }) {
return { city, temperature: 18, unit, conditions: "cloudy" };
}
const messages = [{ role: "user", content: "What is the weather in Paris right now?" }];
let answer = null;
// The API sets no limit on rounds: set your own.
for (let round = 0; round < 5; round++) {
const response = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
messages,
tools,
});
const choice = response.choices[0];
if (choice.finish_reason !== "tool_calls") {
answer = choice.message.content;
break;
}
messages.push(choice.message); // the assistant turn with its tool_calls
for (const call of choice.message.tool_calls) {
const args = JSON.parse(call.function.arguments); // arguments is a JSON string
messages.push({
role: "tool",
tool_call_id: call.id,
content: JSON.stringify(getWeather(args)),
});
}
}
console.log(answer); # 1. Send the conversation with the tools.
curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"}
],
"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"]
}
}
}]
}'
# 2. Run the function yourself, then send the assistant turn and the result.
# Use the id of the call you received.
curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"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\"}"}
],
"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"]
}
}
}]
}' Impendulo yokuqala ayiphenduli umbuzo. Icela ukubiza:
{
"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"]
}
}
} {
"type": "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"]
}
} {
"name": "get_weather",
"description": "Get the current weather for a city.",
"input_schema": {
"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\"}"
}
}
]
}
} {
"output": [
{
"id": "fc_3d2c1b0a9f8e4d7c6b5a4f3e2d1c0b9a",
"type": "function_call",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}",
"status": "completed"
}
]
} {
"stop_reason": "tool_use",
"content": [
{
"type": "tool_use",
"id": "toolu_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"input": {"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.
{
"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\"}"
}
]
} {
"input": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{
"type": "function_call",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
},
{
"type": "function_call_output",
"call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"output": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"
}
]
} {
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
"name": "get_weather",
"input": {"city": "Paris"}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_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_idku-/v1/chat/completions, i-call_idku-/v1/responses, i-tool_use_idku-/v1/messages. - Umphumela ungumbhalo. Shintsha into ibe yi-string ye-JSON ye-
content(i-outputku-/v1/responses). Ku-/v1/messagesi-contentye-block ye-tool_resultiyi-string noma uhlu lwama-block ombhalo. - Esinyathelweni se-assistant, i-
function.argumentsihlala 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-litene-shannon-2-prozisebenzisa i-temperatureezenzakalelayo engu-0.2. Thumela i-temperatureukuze 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