Aðgerðaköll
Lýstu föllunum þínum í beiðninni og líkanið svarar með köllunum sem það vill láta gera. Kóðinn þinn keyrir þau og sendir niðurstöðurnar til baka: API skilar tólakölum og keyrir ekkert tól sjálft.
POST https://api.shannon-ai.com/v1/chat/completions
Dæmin á þessari síðu nota /v1/chat/completions. Sama lykkja keyrir á /v1/responses og /v1/messages; þar sem snið skrifar eitthvað öðruvísi sýna kaflarnir hér á eftir öll þrjú.
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"]
}
}
}]
}' Fyrsta svarið svarar ekki spurningunni. Það biður um kall:
{
"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}
}
} Eftir að þú sendir niðurstöðuna er næsta svar venjulegt svar: message.content geymir textann og finish_reason er stop.
Lykkjan, skref fyrir skref
| Skref | Hver | Hvað gerist |
|---|---|---|
| 1 | Þú | Sendu messages ásamt tools, listanum yfir föllin sem líkanið má biðja um. |
| 2 | Líkan | Svarið ber tool_calls og finish_reason: "tool_calls". Hvert kall nefnir fall og gefur röksemdir þess. |
| 3 | Þú | Þáttaðu arguments hvers kalls og keyrðu fallið þitt. |
| 4 | Þú | Bættu assistant-skilaboðunum og einum tool skilaboðum á kall við messages og sendu síðan beiðnina aftur með sömu tools. |
| 5 | Líkan | Líkanið svarar með texta og finish_reason: "stop", eða biður um fleiri köll. Farðu í því tilviki aftur í skref 3. |
Ein beiðni er ein lota líkansins. API geymir ekkert samtal milli beiðna og setur engan fjölda umferða: kóðinn þinn heldur messages og ákveður hvenær á að hætta.
Tól skilgreind
tools er fylki með eina færslu á fall. Öll líkön í skránni taka við því; GET /v1/models sýnir capabilities.tools: true fyrir hvert auðkenni.
| Reitur | Gerð | Lýsing |
|---|---|---|
type | string | Alltaf function. |
function.name | string | Heitið sem líkanið notar þegar það biður um þetta fall. Skylda. |
function.description | string | Hvað fallið gerir, á einföldu máli. |
function.parameters | object | Röksemdirnar sem JSON Schema með type: "object" efst. Sjá Lykilorð skema hér á eftir. |
Hver endapunktur hefur sína eigin ritun tóls. Sendu þá sem tilheyrir endapunktinum sem þú kallar á:
{
"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
tool_choice segir hvort líkanið megi, eða verði, að kalla á tól. Það er aðeins lesið ásamt tools.
| Gildi | Lýsing | Notað af |
|---|---|---|
"auto" | Líkanið ákveður hvort það svarar með texta eða kallar á tól. Þetta er sjálfgefið. | Öll líkön |
"required" | Svarið kallar á að minnsta kosti eitt tól. | Hýst líkön með opnum þyngdum |
{"type": "function", "function": {"name": "get_weather"}} | Svarið kallar á þetta fall. Heitið verður að vera eitt af föllunum í tools. Köll á önnur föll eru undanskilin svarinu. | Hýst líkön með opnum þyngdum |
Shannon-líkönin (shannon-*) ákveða í hverri beiðni, eins og með auto.
Með required eða nefndu falli skaltu lesa finish_reason áður en þú lest tool_calls. Þegar líkanið gerir ekkert kall er svarið textasvar með finish_reason: "stop".
| Merking | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Líkanið ákveður | "auto" | "auto" | {"type": "auto"} |
| Kalla á að minnsta kosti eitt tól | "required" | "required" | {"type": "any"} |
| Kalla á eitt nefnt fall | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Samþykkt vegna samhæfni: tool_choice: "none" og parallel_tool_calls. Fyrir lotu án tólakalla skaltu senda beiðnina án tools.
Tólakall í svarinu
| Reitur | Gerð | Lýsing |
|---|---|---|
finish_reason | string | tool_calls þegar svarið ber að minnsta kosti eitt kall. |
message.tool_calls | array | Ein færsla á kall. Reiturinn er aðeins til staðar þegar líkanið bað um kall. |
tool_calls[].id | string | call_ og síðan 32 sextándakerfisstafir. Sendu það til baka sem tool_call_id með niðurstöðunni. |
tool_calls[].type | string | Alltaf function. |
tool_calls[].function.name | string | Fallið sem á að keyra. |
tool_calls[].function.arguments | string | Röksemdirnar sem JSON-strengur, "{}" þegar þær eru engar. Þáttaðu hann áður en þú notar hann. |
message.content | string | null | null þegar svarið geymir aðeins köll. Hýst líkön með opnum þyngdum geta skilað texta við hlið kallanna; Shannon-líkönin skila null. |
Sama kallið á hverju sniði. Á /v1/responses er það function_call færsla í output, með arguments sem JSON-streng. Á /v1/messages er það tool_use efnisblokk þar sem input er JSON-hlutur, id byrjar á toolu_ og stop_reason er 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"}
}
]
} Mörg köll í einni lotu
Svar getur borið mörg köll. Keyrðu þau öll og sendu eina niðurstöðu fyrir hvert kall, hverja með sínu tool_call_id, í næstu beiðni.
Hýst líkön með opnum þyngdum skila hverju ólíku kalli einu sinni: tvö köll með sama heiti og sömu röksemdir berast sem eitt.
Streymd tólakall
Með stream: true berst kall í einu lagi: búturinn geymir allan arguments strenginn, svo engin brot þarf að tengja saman. index telur köll lotunnar frá 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
}
]
} | Endapunktur | Hvað berst |
|---|---|
/v1/chat/completions | Einn chat.completion.chunk á kall, með kallið í delta.tool_calls[0]. Síðasti búturinn hefur finish_reason: "tool_calls" og usage. |
/v1/responses | Á kall: response.output_item.added (function_call færsla með tómt arguments), response.function_call_arguments.delta (allur strengurinn), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Á kall: content_block_start (tool_use blokk með tómt input), eitt content_block_delta þar sem input_json_delta.partial_json er allur röksemdatextinn, content_block_stop. message_delta ber síðan stop_reason: "tool_use". |
Á shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro og shannon-coder-1 skilar streymd beiðni sem ber tools svartextanum í einu content delta í lok lotunnar. Streymi
Niðurstöður sendar til baka
Seinni beiðnin endurtekur samtalið og bætir við tveimur hlutum: assistant-lotunni sem bað um köllin og einni niðurstöðu á kall.
{
"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\"}"
}
]
}
]
} - Sendu assistant-lotuna til baka eins og þú fékkst hana, á undan niðurstöðunum. Hver niðurstaða er pöruð við kall sitt með auðkenni:
tool_call_idá/v1/chat/completions,call_idá/v1/responses,tool_use_idá/v1/messages. - Niðurstaða er texti. Raðaðu hlut í JSON-streng fyrir
content(outputá/v1/responses). Á/v1/messagesercontentítool_resultblokk strengur eða listi af textablokkum. - Í assistant-lotunni helst
function.argumentsJSON-strengur, nákvæmlega eins og hann barst. - Samtalið má enda á tólaniðurstöðu. Engin ný notandaskilaboð eru nauðsynleg: líkanið heldur áfram frá niðurstöðunni.
- Þegar fallið þitt mistekst skaltu senda bilunina sem niðurstöðutexta. Líkanið getur þá greint frá henni eða beðið um annað kall.
Lykilorð skema
parameters (input_schema á /v1/messages) er JSON Schema. Shannon 3 fjölskyldan (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) og hýst líkön með opnum þyngdum fá það eins og þú sendir það.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro og shannon-coder-1 fá þessa hlutmengi, á öllum þremur endapunktunum:
| Meðferð | Lykilorð |
|---|---|
| Lesið eins og sent | Öll lykilorð sem eru ekki nefnd í línunum hér fyrir neðan, til dæmis type, properties, required, items, enum, description, minimum, maximum, anyOf og allOf, á öllum stigum skemans. |
format | Lesið fyrir gildin int32, int64, float, double, byte, date, date-time og enum. |
oneOf | Lesið sem anyOf. |
| Ekki hluti af skemanu sem þessi líkön fá | $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 og exclusiveMaximum þegar þau eru tölur; önnur gildi format. |
Hegðun og mörk
- API setur engin hámörk á fjölda tóla og engin hámörk á fjölda umferða.
- Beiðnameginmál getur verið allt að 32 MiB, og samtalið með niðurstöðum sínum verður að komast fyrir í samhengisglugga líkansins.
- Þegar beiðni ber
toolsnotashannon-1.6-lite,shannon-1.6-pro,shannon-2-liteogshannon-2-prosjálfgefiðtemperature0.2. Sendutemperaturetil að stilla annað gildi. - Hver umferð er sjálfstæð beiðni: hún dregur af stöðunni þinni og telst með í flóðvörn eins og hver önnur beiðni. Mörk og staða
Villur
Tólakall er venjulegt svar með stöðuna 200. Þessar villur varða beiðnina sjálfa:
| Staða | Gerð | Skilaboð | Hvenær |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model er ekki auðkenni af útgefna listanum. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools er ekki fylki, eða annar reitur hefur rangt JSON-gagnatag. |
413 | invalid_request_error | Failed to buffer the request body: … | Beiðnameginmálið er stærra en 32 MiB. Villan ber code: "request_too_large". |
Líkanið skrifar röksemdirnar. Athugaðu þær gegn skemanu þínu áður en þú keyrir fallið, eins og þú athugaðir hvert annað utanaðkomandi inntak.
Auðkenning, staða og þjónsvillur eru þær sömu og fyrir allar beiðnir. Villumeðhöndlun