Call gnìomh
Mìnich na functions agad san iarrtas agus freagraidh am modail leis na gairmean a tha e ag iarraidh a dhèanamh. Ruithidh an còd agad iad agus cuiridh e na toraidhean air ais: bheir an API gairmean inneil air ais agus chan eil e fhèin a’ ruith inneal.
POST https://api.shannon-ai.com/v1/chat/completions
Bidh na sampaill air an duilleag seo a’ cleachdadh /v1/chat/completions. Ruithidh an aon lùb air /v1/responses agus /v1/messages; far a bheil cruth a’ litreachadh rudeigin eadar-dhealaichte, seallaidh na h-earrannan gu h-ìosal na trì.
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"]
}
}
}]
}' Chan eil a’ chiad fhreagairt a’ freagairt na ceist. Tha i ag iarraidh gairm:
{
"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}
}
} Às dèidh dhut an toradh a chur, tha an ath fhreagairt na fhreagairt àbhaisteach: tha an teacsa ann an message.content agus is e stop an finish_reason.
An lùb, ceum air cheum
| Ceum | Cò | Dè thachras |
|---|---|---|
| 1 | Thu fhèin | Cuir messages còmhla ri tools, liosta nan functions a dh’fhaodas am modail iarraidh. |
| 2 | Modail | Tha tool_calls agus finish_reason: "tool_calls" sa fhreagairt. Ainmichidh gach gairm function agus bheir i na h-argamaidean aice. |
| 3 | Thu fhèin | Parsaich na arguments aig gach gairm agus ruith an function agad. |
| 4 | Thu fhèin | Cuir teachdaireachd an assistant agus aon teachdaireachd tool gach gairm ri messages, an uair sin cuir an t-iarrtas a-rithist leis na h-aon tools. |
| 5 | Modail | Freagraidh am modail ann an teacsa le finish_reason: "stop", no iarraidh e barrachd ghairmean. Anns a’ chùis sin, till gu ceum 3. |
Is e aon iarrtas aon tionndadh modail. Chan eil an API a’ cumail còmhradh eadar iarrtasan agus chan eil e a’ suidheachadh àireamh chuairtean: tha messages aig an chòd agad agus cho-dhùineas e cuin a stadas e.
A’ mìneachadh innealan
Is e array a th’ ann an tools le aon inntrigeadh gach function. Gabhaidh gach modail dhen chatalog ris; bheir GET /v1/models cunntas air capabilities.tools: true airson gach id.
| Raon | Seòrsa | Tuairisgeul |
|---|---|---|
type | string | An-còmhnaidh function. |
function.name | string | An t-ainm a chleachdas am modail nuair a dh’iarras e an function seo. Riatanach. |
function.description | string | Dè a nì an function, ann am briathran sìmplidh. |
function.parameters | object | Na h-argamaidean mar JSON Schema le type: "object" aig a’ mhullach. Faic Facail-iuchrach schema gu h-ìosal. |
Tha litreachadh fhèin aig gach endpoint airson inneal. Cuir am fear a bhuineas dhan endpoint a ghairmeas tu:
{
"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
Innsidh tool_choice an fhaod am modail, no am feum e, inneal a ghairm. Thèid a leughadh a-mhàin còmhla ri tools.
| Luach | Tuairisgeul | Air a chur an sàs le |
|---|---|---|
"auto" | Co-dhùineas am modail an freagair e ann an teacsa no an gairm e inneal. Is e seo a’ bhun-roghainn. | A h-uile modail |
"required" | Gairmidh am freagairt co-dhiù aon inneal. | Modailean open-weight hosted |
{"type": "function", "function": {"name": "get_weather"}} | Gairmidh am freagairt an function seo. Feumaidh an t-ainm a bhith air aon dhe na functions ann an tools. Thèid gairmean gu functions eile fhàgail a-mach às a’ fhreagairt. | Modailean open-weight hosted |
Co-dhùineas na modailean Shannon (shannon-*) anns gach iarrtas, mar le auto.
Le required no function ainmichte, leugh finish_reason mus leugh thu tool_calls. Mura toir am modail gairm, tha am freagairt na fhreagairt teacsa le finish_reason: "stop".
| Brìgh | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Co-dhùineas am modail | "auto" | "auto" | {"type": "auto"} |
| Gairm co-dhiù aon inneal | "required" | "required" | {"type": "any"} |
| Gairm aon function ainmichte | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Air aontachadh airson co-chòrdalachd: tool_choice: "none" agus parallel_tool_calls. Airson tionndadh gun ghairmean inneil, cuir an t-iarrtas gun tools.
Gairmean inneil san fhreagairt
| Raon | Seòrsa | Tuairisgeul |
|---|---|---|
finish_reason | string | tool_calls nuair a tha co-dhiù aon ghairm san fhreagairt. |
message.tool_calls | array | Aon inntrigeadh gach gairm. Tha an raon an làthair a-mhàin nuair a dh’iarr am modail gairm. |
tool_calls[].id | string | call_ agus an uair sin 32 caractar sia-deugach. Cuir air ais e mar tool_call_id leis an toradh. |
tool_calls[].type | string | An-còmhnaidh function. |
tool_calls[].function.name | string | An function ri ruith. |
tool_calls[].function.arguments | string | Na h-argamaidean mar shreang JSON, "{}" nuair nach eil gin ann. Parsaich e mus cleachd thu e. |
message.content | string | null | null nuair nach eil ach gairmean san fhreagairt. Faodaidh na modailean open-weight hosted teacsa a thilleadh ri taobh nan gairmean; tillidh na modailean Shannon null. |
An aon ghairm anns gach cruth. Air /v1/responses is e nì function_call de output a th’ ann, le arguments mar shreang JSON. Air /v1/messages is e bloc susbaint tool_use a th’ ann aig a bheil input na nì JSON, tòisichidh id le toolu_, agus is e tool_use an stop_reason.
{
"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"}
}
]
} Grunn ghairmean ann an aon tionndadh
Faodaidh grunn ghairmean a bhith ann am freagairt. Ruith gach tè dhiubh agus cuir aon toradh gach gairm, gach fear len tool_call_id fhèin, san ath iarrtas.
Tillidh na modailean open-weight hosted gach gairm sònraichte aon turas: thig dà ghairm leis an aon ainm agus na h-aon argamaidean mar aon.
Gairmean inneil streamte
Le stream: true, thig gairm na aon phìos: tha an sreang arguments slàn anns a’ chunk, agus mar sin chan eil criomagan ri cheangal. Cunntaidh index gairmean an tionndaidh o 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
}
]
} | Endpoint | Dè a thig |
|---|---|
/v1/chat/completions | Aon chat.completion.chunk gach gairm, leis a’ ghairm ann an delta.tool_calls[0]. Tha finish_reason: "tool_calls" agus usage aig an chunk mu dheireadh. |
/v1/responses | Gach gairm: response.output_item.added (nì function_call le arguments falamh), response.function_call_arguments.delta (an sreang slàn), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Gach gairm: content_block_start (bloc tool_use le input falamh), aon content_block_delta aig a bheil input_json_delta.partial_json mar an teacsa argamaidean slàn, content_block_stop. An uair sin bidh stop_reason: "tool_use" aig message_delta. |
Air shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1, lìbhrigidh iarrtas streamte a bheir tools teacsa a fhreagairt ann an aon delta content aig deireadh an tionndaidh. Sruthadh
A’ cur thoraidhean air ais
Ath-aithnichidh an dàrna iarrtas an còmhradh agus cuiridh e dà rud ris: tionndadh an assistant a dh’iarr na gairmean, agus aon toradh gach gairm.
{
"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\"}"
}
]
}
]
} - Cuir tionndadh an assistant air ais mar a fhuair thu e, ron toraidhean. Thèid gach toradh a mhaidseadh ris a’ ghairm aige le id:
tool_call_idair/v1/chat/completions,call_idair/v1/responses,tool_use_idair/v1/messages. - Is e teacsa a th’ ann an toradh. Dèan sreang JSON de nì airson
content(outputair/v1/responses). Air/v1/messagesis e sreang no liosta de bhlocaichean teacsacontentbloctool_result. - Ann an tionndadh an assistant, fanaidh
function.argumentsna shreang JSON, dìreach mar a thàinig e. - Faodaidh an còmhradh crìochnachadh le toradh inneil. Chan eil feum air teachdaireachd ùr neach-cleachdaidh: leanaidh am modail on toradh.
- Nuair a dh’fhailicheas an function agad, cuir am fàilligeadh mar theacsa an toraidh. Faodaidh am modail aithris air no gairm eile iarraidh an uair sin.
Facail-iuchrach schema
Is e JSON Schema parameters (input_schema air /v1/messages). Gheibh teaghlach Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) agus na modailean open-weight hosted e mar a chuireas tu e.
Gheibh shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1 am fo-sheata seo, air na trì endpoints:
| Làimhseachadh | Facail-iuchrach |
|---|---|
| Air a leughadh mar a chaidh a chur | A h-uile facal-iuchrach nach eil air ainmeachadh anns na sreathan gu h-ìosal, mar eisimpleir type, properties, required, items, enum, description, minimum, maximum, anyOf agus allOf, aig gach ìre dhen schema. |
format | Air a leughadh airson na luachan int32, int64, float, double, byte, date, date-time agus enum. |
oneOf | Air a leughadh mar anyOf. |
| Chan eil pàirt dhen schema a gheibh na modailean seo | $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 agus exclusiveMaximum nuair as e àireamhan a th’ annta; luachan eile de format. |
Giùlan agus crìochan
- Chan eil an API a’ suidheachadh uas-àireamh innealan no uas-àireamh chuairtean.
- Faodaidh bodhaig iarrtais a bhith suas gu 32 MiB, agus feumaidh an còmhradh leis na toraidhean aige a bhith a’ freagairt ri uinneag cho-theacsa a’ mhodail.
- Nuair a bhios
toolsaig iarrtas, cleachdaidhshannon-1.6-lite,shannon-1.6-pro,shannon-2-liteagusshannon-2-protemperaturebun-roghainn 0.2. Cuirtemperaturegus luach eile a shuidheachadh. - Tha gach cuairt na iarrtas fa leth: tarraingidh e às do bhalance agus thèid a chunntadh airson dìon thar-thuiltidh mar iarrtas sam bith eile. Crìochan agus balance
Mearachdan
Tha gairm inneil na freagairt àbhaisteach le staid 200. Buinidh na mearachdan seo ris an iarrtas fhèin:
| Staid | Seòrsa | Teachdaireachd | Cuin |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | Chan e id air an liosta fhoillsichte a th’ ann an model. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Chan e array a th’ ann an tools, no tha seòrsa JSON ceàrr air raon eile. |
413 | invalid_request_error | Failed to buffer the request body: … | Tha bodhaig an iarrtais nas motha na 32 MiB. Tha code: "request_too_large" sa mhearachd. |
Sgrìobhaidh am modail na h-argamaidean. Dearbh iad an aghaidh do schema mus ruith thu an function, mar a dhearbhadh tu input sam bith o‘n taobh a-muigh.
Tha mearachdan dearbhaidh, balance agus server mar a tha iad airson gach iarrtas. Làimhseachadh mearachd