Thirrje funksionesh
Përshkruani funksionet tuaja në kërkesë dhe modeli përgjigjet me thirrjet që dëshiron të bëhen. Kodi juaj i ekzekuton dhe dërgon rezultatet mbrapsht: API-ja kthen thirrje mjetesh dhe vetë nuk ekzekuton asnjë mjet.
POST https://api.shannon-ai.com/v1/chat/completions
Shembujt në këtë faqe përdorin /v1/chat/completions. I njëjti cikël funksionon në /v1/responses dhe /v1/messages; ku një format e shkruan diçka ndryshe, seksionet më poshtë i tregojnë të tri.
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"]
}
}
}]
}' Përgjigjja e parë nuk i përgjigjet pyetjes. Kërkon një thirrje:
{
"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}
}
} Pasi dërgoni rezultatin, përgjigjja tjetër është një përgjigje e zakonshme: message.content mban tekstin dhe finish_reason është stop.
Cikli, hap pas hapi
| Hapi | Kush | Çfarë ndodh |
|---|---|---|
| 1 | Ju | Dërgoni messages së bashku me tools, listën e funksioneve që modeli mund të kërkojë. |
| 2 | Modeli | Përgjigjja mban tool_calls dhe finish_reason: "tool_calls". Çdo thirrje emërton një funksion dhe jep argumentet e tij. |
| 3 | Ju | Parsoni arguments e çdo thirrjeje dhe ekzekutoni funksionin tuaj. |
| 4 | Ju | Shtoni te messages mesazhin e assistant dhe një mesazh tool për çdo thirrje, pastaj dërgojeni kërkesën përsëri me të njëjtat tools. |
| 5 | Modeli | Modeli përgjigjet me tekst me finish_reason: "stop", ose kërkon thirrje të tjera. Në atë rast kthehuni te hapi 3. |
Një kërkesë është një radhë e modelit. API-ja nuk mban bisedë mes kërkesave dhe nuk cakton numër raundesh: kodi juaj mban messages dhe vendos kur të ndalojë.
Përcaktimi i mjeteve
tools është një varg me një hyrje për funksion. Çdo model i katalogut e pranon; GET /v1/models raporton capabilities.tools: true për çdo id.
| Fusha | Lloji | Përshkrimi |
|---|---|---|
type | string | Gjithmonë function. |
function.name | string | Emri që përdor modeli kur kërkon këtë funksion. I detyrueshëm. |
function.description | string | Çfarë bën funksioni, në gjuhë të thjeshtë. |
function.parameters | object | Argumentet si JSON Schema me type: "object" në krye. Shihni Fjalët kyçe të skemës më poshtë. |
Çdo endpoint ka shkrimin e vet të një mjeti. Dërgoni atë që i përket endpoint-it që thërrisni:
{
"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 thotë nëse modeli mund ose duhet të thërrasë një mjet. Lexohet vetëm së bashku me tools.
| Vlera | Përshkrimi | Zbatohet nga |
|---|---|---|
"auto" | Modeli vendos nëse do të përgjigjet me tekst ose do të thërrasë një mjet. Kjo është parazgjedhja. | Të gjitha modelet |
"required" | Përgjigjja thërret të paktën një mjet. | Modele open-weight të hostuara |
{"type": "function", "function": {"name": "get_weather"}} | Përgjigjja thërret këtë funksion. Emri duhet të jetë një nga funksionet te tools. Thirrjet e funksioneve të tjera lihen jashtë përgjigjes. | Modele open-weight të hostuara |
Modelet Shannon (shannon-*) vendosin në çdo kërkesë, si me auto.
Me required ose një funksion të emërtuar, lexoni finish_reason para se të lexoni tool_calls. Kur modeli nuk prodhon thirrje, përgjigjja është një përgjigje teksti me finish_reason: "stop".
| Kuptimi | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Modeli vendos | "auto" | "auto" | {"type": "auto"} |
| Thirr të paktën një mjet | "required" | "required" | {"type": "any"} |
| Thirr një funksion të emërtuar | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Pranohen për pajtueshmëri: tool_choice: "none" dhe parallel_tool_calls. Për një radhë pa thirrje mjetesh, dërgojeni kërkesën pa tools.
Thirrjet e mjeteve në përgjigje
| Fusha | Lloji | Përshkrimi |
|---|---|---|
finish_reason | string | tool_calls kur përgjigjja mban të paktën një thirrje. |
message.tool_calls | array | Një hyrje për thirrje. Fusha është e pranishme vetëm kur modeli ka kërkuar një thirrje. |
tool_calls[].id | string | call_ e ndjekur nga 32 karaktere heksadecimale. Dërgojeni mbrapsht si tool_call_id me rezultatin. |
tool_calls[].type | string | Gjithmonë function. |
tool_calls[].function.name | string | Funksioni që do të ekzekutohet. |
tool_calls[].function.arguments | string | Argumentet si string JSON, "{}" kur nuk ka. Parsoni para përdorimit. |
message.content | string | null | null kur përgjigjja mban vetëm thirrje. Modelet open-weight të hostuara mund të kthejnë tekst pranë thirrjeve; modelet Shannon kthejnë null. |
E njëjta thirrje në çdo format. Në /v1/responses është një element function_call i output, me arguments si string JSON. Në /v1/messages është një bllok përmbajtjeje tool_use ku input është objekt JSON, id fillon me toolu_, dhe stop_reason është 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"}
}
]
} Disa thirrje në një radhë
Një përgjigje mund të mbajë disa thirrje. Ekzekutoni të gjitha dhe dërgoni një rezultat për thirrje, secili me tool_call_id të vet, në kërkesën tjetër.
Modelet open-weight të hostuara e kthejnë çdo thirrje të veçantë një herë: dy thirrje me të njëjtin emër dhe të njëjtat argumente arrijnë si një.
Thirrje mjetesh me stream
Me stream: true, një thirrje arrin në një copë të vetme: pjesa mban stringun e plotë arguments, kështu që nuk ka fragmente për t'u bashkuar. index i numëron thirrjet e radhës nga 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 | Çfarë arrin |
|---|---|
/v1/chat/completions | Një chat.completion.chunk për thirrje, me thirrjen te delta.tool_calls[0]. Pjesa e fundit ka finish_reason: "tool_calls" dhe usage. |
/v1/responses | Për thirrje: response.output_item.added (një element function_call me arguments bosh), response.function_call_arguments.delta (i gjithë stringu), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Për thirrje: content_block_start (një bllok tool_use me input bosh), një content_block_delta ku input_json_delta.partial_json është i gjithë teksti i argumenteve, content_block_stop. Pastaj message_delta mban stop_reason: "tool_use". |
Te shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro dhe shannon-coder-1, një kërkesë me stream që mban tools e jep tekstin e përgjigjes në një delta content në fund të radhës. Transmetim
Dërgimi i rezultateve mbrapsht
Kërkesa e dytë e përsërit bisedën dhe shton dy gjëra: radhën e assistant që kërkoi thirrjet, dhe një rezultat për çdo thirrje.
{
"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\"}"
}
]
}
]
} - Dërgojeni radhën e assistant mbrapsht siç e morët, para rezultateve. Çdo rezultat lidhet me thirrjen e vet sipas id-së:
tool_call_idnë/v1/chat/completions,call_idnë/v1/responses,tool_use_idnë/v1/messages. - Një rezultat është tekst. Serializojeni një objekt në string JSON për
content(outputnë/v1/responses). Në/v1/messagescontenti një bllokutool_resultështë string ose listë blloqesh teksti. - Në radhën e assistant,
function.argumentsmbetet string JSON, saktësisht siç arriti. - Biseda mund të mbarojë me një rezultat mjeti. Nuk nevojitet mesazh i ri përdoruesi: modeli vazhdon nga rezultati.
- Kur funksioni juaj dështon, dërgojeni dështimin si tekst rezultati. Modeli pastaj mund ta raportojë ose të kërkojë një thirrje tjetër.
Fjalët kyçe të skemës
parameters (input_schema në /v1/messages) është një JSON Schema. Familja Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) dhe modelet open-weight të hostuara e marrin siç e dërgoni.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro dhe shannon-coder-1 e marrin këtë nëngrup, në të tri endpoint-et:
| Trajtimi | Fjalët kyçe |
|---|---|
| Lexohet siç dërgohet | Çdo fjalë kyçe që nuk emërtohet në rreshtat më poshtë, për shembull type, properties, required, items, enum, description, minimum, maximum, anyOf dhe allOf, në çdo nivel të skemës. |
format | Lexohet për vlerat int32, int64, float, double, byte, date, date-time dhe enum. |
oneOf | Lexohet si anyOf. |
| Nuk është pjesë e skemës që marrin këta modele | $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 dhe exclusiveMaximum kur janë numra; vlera të tjera të format. |
Sjellja dhe kufijtë
- API-ja nuk cakton numër maksimal mjetesh dhe as numër maksimal raundesh.
- Trupi i një kërkese mund të jetë deri në 32 MiB, dhe biseda me rezultatet e saj duhet të ngjitet në dritaren e kontekstit të modelit.
- Kur një kërkesë mban
tools,shannon-1.6-lite,shannon-1.6-pro,shannon-2-litedheshannon-2-propërdorin njëtemperaturetë parazgjedhur 0.2. Dërgonitemperaturepër të caktuar vlerë tjetër. - Çdo raund është kërkesë më vete: tërheq nga bilanci juaj dhe numërohet te mbrojtja nga vërshimi i kërkesave si çdo kërkesë tjetër. Kufijtë dhe bilanci
Gabimet
Një thirrje mjeti është një përgjigje normale me status 200. Këto gabime lidhen me vetë kërkesën:
| Statusi | Lloji | Mesazhi | Kur |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model nuk është id e listës së publikuar. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools nuk është varg, ose një fushë tjetër ka lloj JSON të gabuar. |
413 | invalid_request_error | Failed to buffer the request body: … | Trupi i kërkesës është më i madh se 32 MiB. Gabimi mban code: "request_too_large". |
Argumentet i shkruan modeli. Kontrolloni ato kundrejt skemës suaj para se ta ekzekutoni funksionin, siç do të kontrollonit çdo hyrje nga jashtë.
Gabimet e autentikimit, bilancit dhe serverit janë të njëjta si për çdo kërkesë. Trajtimi i gabimeve