Glaonna Feidhme
Déan cur síos ar d'fheidhmeanna san iarratas agus freagraíonn an múnla leis na glaonna is mian leis a dhéanamh. Ritheann do chód iad agus seolann sé na torthaí ar ais: filleann an API glaonna uirlisí agus ní ritheann sé uirlis é féin.
POST https://api.shannon-ai.com/v1/chat/completions
Úsáideann na samplaí ar an leathanach seo /v1/chat/completions. Ritheann an lúb chéanna ar /v1/responses agus /v1/messages; nuair a litríonn formáid rud éigin ar bhealach difriúil, taispeánann na hailt thíos na trí cheann.
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"]
}
}
}]
}' Ní fhreagraíonn an chéad fhreagra an cheist. Iarrann sé glao:
{
"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}
}
} Tar éis duit an toradh a sheoladh, is gnáthfhreagra é an chéad fhreagra eile: tá an téacs i message.content agus is é stop an finish_reason.
An lúb, céim ar chéim
| Céim | Cé | Cad a tharlaíonn |
|---|---|---|
| 1 | Tusa | Seol messages agus tools le chéile, liosta na bhfeidhmeanna a fhéadfaidh an múnla iarraidh. |
| 2 | Múnla | Iompraíonn an freagra tool_calls agus finish_reason: "tool_calls". Ainmníonn gach glao feidhm agus tugann sé a hargóintí. |
| 3 | Tusa | Parsáil arguments gach glao agus rith d'fheidhm. |
| 4 | Tusa | Cuir an teachtaireacht chúntóra agus teachtaireacht tool amháin in aghaidh gach glao le messages, ansin seol an t-iarratas arís leis na tools chéanna. |
| 5 | Múnla | Freagraíonn an múnla i dtéacs le finish_reason: "stop", nó iarrann sé tuilleadh glaonna. Sa chás sin téigh ar ais go céim 3. |
Is casadh múnla amháin é iarratas amháin. Ní choinníonn an API aon chomhrá idir iarratais agus ní shocraíonn sé aon líon babhtaí: coinníonn do chód messages agus socraíonn sé cathain a stopfaidh sé.
Uirlisí a shainiú
Is eagar é tools le hiontráil amháin in aghaidh gach feidhme. Glacann gach múnla den chatalóg leis; tuairiscíonn GET /v1/models capabilities.tools: true do gach id.
| Réimse | Cineál | Cur síos |
|---|---|---|
type | string | function i gcónaí. |
function.name | string | An t-ainm a úsáideann an múnla nuair a iarrann sé an fheidhm seo. Riachtanach. |
function.description | string | Cad a dhéanann an fheidhm, i dteanga shimplí. |
function.parameters | object | Na hargóintí mar JSON Schema le type: "object" ar bharr. Féach Eochairfhocail scéime thíos. |
Tá litriú uirlise dá cuid féin ag gach críochphointe. Seol an ceann a bhaineann leis an gcríochphointe a ghlaonn tú:
{
"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
Insíonn tool_choice an bhfuil cead ag an múnla uirlis a ghlaoch, nó an gcaithfidh sé. Ní léitear é ach le tools.
| Luach | Cur síos | Curtha i bhfeidhm ag |
|---|---|---|
"auto" | Socraíonn an múnla an bhfreagróidh sé i dtéacs nó an nglaofaidh sé uirlis. Is é seo an réamhshocrú. | Gach múnla |
"required" | Glaonn an freagra uirlis amháin ar a laghad. | Múnlaí open-weight óstáilte |
{"type": "function", "function": {"name": "get_weather"}} | Glaonn an freagra an fheidhm seo. Caithfidh an t-ainm a bheith ar cheann de na feidhmeanna in tools. Fágtar glaonna ar fheidhmeanna eile as an bhfreagra. | Múnlaí open-weight óstáilte |
Socraíonn na múnlaí Shannon (shannon-*) i ngach iarratas, mar a dhéanann auto.
Le required nó feidhm ainmnithe, léigh finish_reason sula léann tú tool_calls. Nuair nach dtáirgeann an múnla aon ghlao, is freagra téacs é an freagra le finish_reason: "stop".
| Brí | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Socraíonn an múnla | "auto" | "auto" | {"type": "auto"} |
| Glaoigh uirlis amháin ar a laghad | "required" | "required" | {"type": "any"} |
| Glaoigh feidhm ainmnithe amháin | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Glactar leo ar mhaithe le comhoiriúnacht: tool_choice: "none" agus parallel_tool_calls. Le haghaidh casaidh gan glaonna uirlisí, seol an t-iarratas gan tools.
Glaonna uirlisí san fhreagra
| Réimse | Cineál | Cur síos |
|---|---|---|
finish_reason | string | tool_calls nuair a iompraíonn an freagra glao amháin ar a laghad. |
message.tool_calls | array | Iontráil amháin in aghaidh gach glao. Tá an réimse ann amháin nuair a d'iarr an múnla glao. |
tool_calls[].id | string | call_ agus 32 charachtar heicsidheachúlacha ina dhiaidh. Seol ar ais é mar tool_call_id leis an toradh. |
tool_calls[].type | string | function i gcónaí. |
tool_calls[].function.name | string | An fheidhm atá le rith. |
tool_calls[].function.arguments | string | Na hargóintí mar shreang JSON, "{}" nuair nach bhfuil aon cheann ann. Parsáil é roimh úsáid. |
message.content | string | null | null nuair nach bhfuil sa fhreagra ach glaonna. Is féidir leis na múnlaí open-weight óstáilte téacs a fhilleadh in aice leis na glaonna; filleann na múnlaí Shannon null. |
An glao céanna i ngach formáid. Ar /v1/responses is mír function_call de output é, le arguments mar shreang JSON. Ar /v1/messages is bloc ábhair tool_use é a bhfuil réad JSON mar input air, tosaíonn a id le toolu_, agus is é 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"}
}
]
} Roinnt glaonna i gcasadh amháin
Is féidir le freagra roinnt glaonna a iompar. Rith gach ceann acu agus seol toradh amháin in aghaidh gach glao, gach ceann lena tool_call_id féin, san iarratas dár gcionn.
Filleann na múnlaí open-weight óstáilte gach glao ar leith uair amháin: tagann dhá ghlao leis an ainm céanna agus na hargóintí céanna mar cheann amháin.
Glaonna uirlisí sruthaithe
Le stream: true, tagann glao i bpíosa amháin: tá an tsreang arguments iomlán sa phíosa, mar sin níl aon blúirí le nascadh. Comhaireann index glaonna an chasaidh ó 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
}
]
} | Críochphointe | Cad a thagann |
|---|---|
/v1/chat/completions | chat.completion.chunk amháin in aghaidh gach glao, agus an glao i delta.tool_calls[0]. Tá finish_reason: "tool_calls" agus usage sa phíosa deireanach. |
/v1/responses | In aghaidh gach glao: response.output_item.added (mír function_call le arguments folamh), response.function_call_arguments.delta (an tsreang iomlán), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | In aghaidh gach glao: content_block_start (bloc tool_use le input folamh), content_block_delta amháin a bhfuil input_json_delta.partial_json ann mar théacs iomlán na n-argóintí, content_block_stop. Ansin iompraíonn message_delta stop_reason: "tool_use". |
Ar shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1, seachadann iarratas sruthaithe a iompraíonn tools téacs a fhreagra i delta content amháin ag deireadh an chasaidh. Sruthú
Torthaí a sheoladh ar ais
Athdhéanann an dara hiarratas an comhrá agus cuireann sé dhá rud leis: an casadh cúntóra a d'iarr na glaonna, agus toradh amháin in aghaidh gach glao.
{
"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\"}"
}
]
}
]
} - Seol an casadh cúntóra ar ais mar a fuair tú é, roimh na torthaí. Meaitseáiltear gach toradh lena ghlao de réir id:
tool_call_idar/v1/chat/completions,call_idar/v1/responses,tool_use_idar/v1/messages. - Is téacs é toradh. Sraithe réad go sreang JSON do
content(outputar/v1/responses). Ar/v1/messagesis sreang nó liosta bloc téacs écontentbloctool_result. - Sa chasadh cúntóra, fanann
function.argumentsmar shreang JSON, díreach mar a tháinig sé. - Is féidir leis an gcomhrá deireadh le toradh uirlise. Ní theastaíonn teachtaireacht úsáideora nua: leanann an múnla ón toradh.
- Nuair a theipeann ar d'fheidhm, seol an teip mar théacs an toraidh. Ansin is féidir leis an múnla í a thuairisciú nó glao eile a iarraidh.
Eochairfhocail scéime
Is JSON Schema é parameters (input_schema ar /v1/messages). Faigheann teaghlach Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) agus na múnlaí open-weight óstáilte é mar a sheolann tú é.
Faigheann shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1 an fholimistir seo, ar na trí chríochphointe:
| Cóireáil | Eochairfhocail |
|---|---|
| Léite mar a seoladh | Gach eochairfhocal nach ainmnítear sna sraitheanna thíos, mar shampla type, properties, required, items, enum, description, minimum, maximum, anyOf agus allOf, ar gach leibhéal den scéim. |
format | Léitear do na luachanna int32, int64, float, double, byte, date, date-time agus enum. |
oneOf | Léitear mar anyOf. |
| Nach cuid den scéim a fhaigheann na múnlaí 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 is uimhreacha iad; luachanna eile de format. |
Iompar agus teorainneacha
- Ní shocraíonn an API uasmhéid uirlisí ná uasmhéid babhtaí.
- Is féidir le corp iarratais a bheith suas le 32 MiB, agus caithfidh an comhrá lena thorthaí a bheith ag luí le fuinneog comhthéacs an mhúnla.
- Nuair a iompraíonn iarratas
tools, úsáideannshannon-1.6-lite,shannon-1.6-pro,shannon-2-liteagusshannon-2-protemperatureréamhshocraithe de 0.2. Seoltemperaturechun luach eile a shocrú. - Is iarratas ar leith é gach babhta: tarraingíonn sé as d'iarmhéid agus comhairtear i leith chosaint tuile é cosúil le haon iarratas eile. Teorainneacha agus iarmhéid
Earráidí
Is gnáthfhreagra le stádas 200 é glao uirlise. Baineann na hearráidí seo leis an iarratas féin:
| Stádas | Cineál | Teachtaireacht | Cathain |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | Ní id den liosta foilsithe é model. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Ní eagar é tools, nó tá cineál JSON mícheart ar réimse eile. |
413 | invalid_request_error | Failed to buffer the request body: … | Tá corp an iarratais níos mó ná 32 MiB. Tá code: "request_too_large" san earráid. |
Scríobhann an múnla na hargóintí. Seiceáil iad i gcoinne do scéime sula ritheann tú an fheidhm, mar a sheicfeá aon ionchur ón taobh amuigh.
Tá earráidí fíordheimhnithe, iarmhéide agus freastalaí mar an gcéanna le gach iarratas. Láimhseáil Earráide