Funktiounsofruff
Beschreift Är Funktiounen an der Ufro, an de Modell äntwert mat de Ruffer, déi en wëll hunn. Äre Code féiert se aus a schéckt d'Resultater zréck: d'API gëtt Tool-Ruffer zréck a féiert selwer kee Tool aus.
POST https://api.shannon-ai.com/v1/chat/completions
D'Beispiller op dëser Säit benotzen /v1/chat/completions. Déiselwecht Loop leeft op /v1/responses an /v1/messages; wou e Format eppes anescht schreift, weisen d'Rubriken ënnen all dräi.
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"]
}
}
}]
}' Déi éischt Äntwert beäntwert d'Fro net. Si freet no engem Ruff:
{
"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}
}
} Nodeems Dir d'Resultat geschéckt hutt, ass déi nächst Äntwert eng normal Äntwert: message.content enthält den Text an finish_reason ass stop.
D'Loop, Schrëtt fir Schrëtt
| Schrëtt | Wien | Wat geschitt |
|---|---|---|
| 1 | Dir | Schéckt messages zesumme mat tools, der Lëscht vun de Funktiounen, no deenen de Modell däerf froen. |
| 2 | Modell | D'Äntwert enthält tool_calls an finish_reason: "tool_calls". All Ruff nennt eng Funktioun a gëtt hir Argumenter. |
| 3 | Dir | Parst d'arguments vun all Ruff a féiert Är Funktioun aus. |
| 4 | Dir | Hänkt d'Assistent-Message an eng tool-Message pro Ruff u messages un, a schéckt dann d'Ufro nach eng Kéier mat deene selwechte tools. |
| 5 | Modell | De Modell äntwert mat Text a mat finish_reason: "stop", oder freet no weidere Ruffer. An deem Fall gitt zréck zu Schrëtt 3. |
Eng Ufro ass een Tour vum Modell. D'API behält keng Konversatioun tëscht Ufroen an setzt keng Zuel u Ronnen: Äre Code hält messages a entscheet, wéini en opheiert.
Tools definéieren
tools ass en Array mat engem Eintrag pro Funktioun. All Modell vum Katalog akzeptéiert et; GET /v1/models mellt capabilities.tools: true fir all ID.
| Feld | Typ | Beschreiwung |
|---|---|---|
type | string | Ëmmer function. |
function.name | string | Den Numm, deen de Modell benotzt, wann en no dëser Funktioun freet. Erfuerderlech. |
function.description | string | Wat d'Funktioun mécht, a ganz normaler Sprooch. |
function.parameters | object | D'Argumenter als JSON Schema mat type: "object" uewen. Kuckt Schema-Schlësselwierder ënnen. |
All Endpoint huet seng eege Schreifweis fir en Tool. Schéckt déi, déi zum Endpoint gehéiert, deen Dir rufft:
{
"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 seet, ob de Modell en Tool däerf, oder muss, ruffen. Et gëtt nëmmen zesumme mat tools gelies.
| Wäert | Beschreiwung | Ugewannt vun |
|---|---|---|
"auto" | De Modell entscheet, ob en mat Text äntwert oder en Tool rifft. Dat ass de Standard. | All Modeller |
"required" | D'Äntwert rifft op d'mannst een Tool. | Hosted Open-Weight-Modeller |
{"type": "function", "function": {"name": "get_weather"}} | D'Äntwert rifft dës Funktioun. Den Numm muss eng vun de Funktiounen an tools sinn. Ruffer vun aneren Funktioune ginn aus der Äntwert erausgelooss. | Hosted Open-Weight-Modeller |
D'Shannon-Modeller (shannon-*) entscheeden bei all Ufro selwer, wéi bei auto.
Liest bei required oder enger genannter Funktioun finish_reason, ier Dir tool_calls liest. Wann de Modell keen Ruff produzéiert, ass d'Äntwert eng Textäntwert mat finish_reason: "stop".
| Bedeitung | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| De Modell entscheet | "auto" | "auto" | {"type": "auto"} |
| Op d'mannst een Tool ruffen | "required" | "required" | {"type": "any"} |
| Eng genannt Funktioun ruffen | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Fir d'Kompatibilitéit akzeptéiert: tool_choice: "none" an parallel_tool_calls. Fir en Tour ouni Tool-Ruffer schéckt d'Ufro ouni tools.
Tool-Ruffer an der Äntwert
| Feld | Typ | Beschreiwung |
|---|---|---|
finish_reason | string | tool_calls, wann d'Äntwert op d'mannst een Ruff enthält. |
message.tool_calls | array | Een Eintrag pro Ruff. D'Feld ass nëmmen do, wann de Modell no engem Ruff gefrot huet. |
tool_calls[].id | string | call_ gefollegt vun 32 hexadezimale Zeechen. Schéckt se als tool_call_id mam Resultat zréck. |
tool_calls[].type | string | Ëmmer function. |
tool_calls[].function.name | string | D'Funktioun, déi soll lafen. |
tool_calls[].function.arguments | string | D'Argumenter als JSON-String, "{}", wann et keng gëtt. Parst se virun der Notzung. |
message.content | string | null | null, wann d'Äntwert just Ruffer enthält. D'Hosted Open-Weight-Modeller kënnen Text niewent de Ruffer zréckgi; d'Shannon-Modeller ginn null zréck. |
Deeselwechte Ruff an all Format. Op /v1/responses ass et en function_call-Item vun output, mat arguments als JSON-String. Op /v1/messages ass et e tool_use-Inhaltsblock, dee säin input als JSON-Objet huet, seng id fänkt mat toolu_ un, an stop_reason ass 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éi Ruffer an engem Tour
Eng Äntwert ka méi Ruffer enthalen. Féiert se all aus a schéckt an der nächster Ufro ee Resultat pro Ruff, all mat sengem eegenen tool_call_id.
D'Hosted Open-Weight-Modeller ginn all verschidde Ruff eemol zréck: zwee Ruffer mam selwechten Numm a mat de selwechten Argumenter kommen als een un.
Gestreamt Tool-Ruffer
Mat stream: true kënnt e Ruff an engem Stéck: de Chunk enthält de kompletten arguments-String, sou datt et keng Fragmenter ze verbannen gëtt. index zielt d'Ruffer vum Tour vun 0 un.
{
"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 | Wat ukënnt |
|---|---|
/v1/chat/completions | Ee chat.completion.chunk pro Ruff, mam Ruff an delta.tool_calls[0]. Dee leschte Chunk huet finish_reason: "tool_calls" an usage. |
/v1/responses | Pro Ruff: response.output_item.added (e function_call-Item mat eidelen arguments), response.function_call_arguments.delta (de ganze String), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Pro Ruff: content_block_start (e tool_use-Block mat eidelem input), een content_block_delta, dee säin input_json_delta.partial_json de ganzen Argumenter-Text ass, content_block_stop. message_delta enthält dann stop_reason: "tool_use". |
Bei shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1 liwwert eng gestreamt Ufro mat tools hiren Äntwert-Text an engem content-Delta um Enn vum Tour. Streaming
Resultater zréckschécken
Déi zweet Ufro widderhëlt d'Konversatioun a füügt zwee Saachen derbäi: den Assistent-Tour, deen d'Ruffer ugefrot huet, an ee Resultat pro Ruff.
{
"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\"}"
}
]
}
]
} - Schéckt den Assistent-Tour esou zréck, wéi Dir en kritt hutt, virun de Resultater. All Resultat gëtt iwwer d'ID mat sengem Ruff verbonnen:
tool_call_idop/v1/chat/completions,call_idop/v1/responses,tool_use_idop/v1/messages. - E Resultat ass Text. Serialiséiert en Objet an e JSON-String fir
content(outputop/v1/responses). Op/v1/messagesass decontentvun engemtool_result-Block e String oder eng Lëscht vun Textblöck. - Am Assistent-Tour bleift
function.argumentse JSON-String, genau sou wéi en ukomm ass. - D'Konversatioun däerf mat engem Tool-Resultat ophalen. Et brauch keng nei Benotzer-Message: de Modell mécht vum Resultat aus weider.
- Wann Är Funktioun feelschléit, schéckt de Feeler als Resultat-Text. De Modell ka sech dann doriwwer äusseren oder en anere Ruff ufroen.
Schema-Schlësselwierder
parameters (input_schema op /v1/messages) ass e JSON Schema. D'Shannon-3-Famill (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) an d'Hosted Open-Weight-Modeller kréien et esou, wéi Dir et schéckt.
shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1 kréien dës Ënnermengt, op allen dräi Endpoints:
| Behandlung | Schlësselwierder |
|---|---|
| Gelies wéi geschéckt | All Schlësselwuert, dat net an den Zeilen ënnendrënner genannt ass, zum Beispill type, properties, required, items, enum, description, minimum, maximum, anyOf an allOf, op all Niveau vum Schema. |
format | Gëtt fir d'Wäerter int32, int64, float, double, byte, date, date-time an enum gelies. |
oneOf | Gëtt als anyOf gelies. |
| Kee Bestanddeel vum Schema, dat dës Modeller kréien | $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 an exclusiveMaximum, wa se Zuelen sinn; aner Wäerter vun format. |
Verhalen a Limiten
- D'API setzt keng Maximalzuel u Tools a keng Maximalzuel u Ronnen.
- E Body vun enger Ufro däerf bis zu 32 MiB grouss sinn, an d'Konversatioun mat hire Resultater muss an d'Kontextfënster vum Modell passen.
- Wann eng Ufro
toolsenthält, benotzeshannon-1.6-lite,shannon-1.6-pro,shannon-2-liteanshannon-2-proen Standard-temperaturevun 0.2. Schéckttemperature, fir en anere Wäert ze setzen. - All Ronn ass eng eege Ufro: si hëlt aus Ärem Solde an zielt fir de Flood-Schutz wéi all aner Ufro. Limiten a Solde
Feeler
E Tool-Ruff ass eng normal Äntwert mam Status 200. Dës Feeler betreffen d'Ufro selwer:
| Status | Typ | Message | Wéini |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | model ass keng ID vun der publizéierter Lëscht. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | tools ass kee Array, oder en anert Feld huet de falsche JSON-Typ. |
413 | invalid_request_error | Failed to buffer the request body: … | De Body vun der Ufro ass méi grouss wéi 32 MiB. De Feeler enthält code: "request_too_large". |
De Modell schreift d'Argumenter. Kontrolléiert se géint Äert Schema, ier Dir d'Funktioun ausféiert, wéi Dir all aneren externen Input géif kontrolléieren.
Authentifikatioun, Solde a Serverfeeler sinn déi selwecht wéi bei all Ufro. Feelerbehandlung