Galw swyddogaeth
Disgrifiwch eich ffwythiannau yn y cais ac mae'r model yn ateb gyda'r galwadau y mae eisiau eu gwneud. Mae eich cod yn eu rhedeg ac yn anfon y canlyniadau yn ôl: mae'r API yn dychwelyd galwadau offer ac nid yw'n rhedeg offeryn ei hun.
POST https://api.shannon-ai.com/v1/chat/completions
Mae'r enghreifftiau ar y dudalen hon yn defnyddio /v1/chat/completions. Mae'r un ddolen yn rhedeg ar /v1/responses a /v1/messages; lle mae fformat yn sillafu rhywbeth yn wahanol, mae'r adrannau isod yn dangos y 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"]
}
}
}]
}' Nid yw'r ateb cyntaf yn ateb y cwestiwn. Mae'n gofyn am alwad:
{
"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}
}
} Ar ôl i chi anfon y canlyniad, mae'r ateb nesaf yn ateb cyffredin: mae message.content yn dal y testun ac mae finish_reason yn stop.
Y ddolen, cam wrth gam
| Cam | Pwy | Beth sy'n digwydd |
|---|---|---|
| 1 | Chi | Anfonwch messages ynghyd â tools, rhestr y ffwythiannau y caiff y model ofyn amdanynt. |
| 2 | Model | Mae'r ateb yn cario tool_calls a finish_reason: "tool_calls". Mae pob galwad yn enwi ffwythiant ac yn rhoi ei ddadleuon. |
| 3 | Chi | Dadansoddwch arguments pob galwad a rhedwch eich ffwythiant. |
| 4 | Chi | Ychwanegwch neges yr assistant ac un neges tool am bob galwad at messages, yna anfonwch y cais eto gyda'r un tools. |
| 5 | Model | Mae'r model yn ateb mewn testun gyda finish_reason: "stop", neu'n gofyn am fwy o alwadau. Yn yr achos hwnnw ewch yn ôl i gam 3. |
Un tro model yw un cais. Nid yw'r API yn cadw sgwrs rhwng ceisiadau ac nid yw'n gosod nifer o rowndiau: mae eich cod yn dal messages ac yn penderfynu pryd i stopio.
Diffinio offer
Arae yw tools gydag un cofnod am bob ffwythiant. Mae pob model yn y catalog yn ei dderbyn; mae GET /v1/models yn adrodd capabilities.tools: true am bob id.
| Maes | Math | Disgrifiad |
|---|---|---|
type | string | Bob amser yn function. |
function.name | string | Yr enw y mae'r model yn ei ddefnyddio pan fydd yn gofyn am y ffwythiant hwn. Gofynnol. |
function.description | string | Beth mae'r ffwythiant yn ei wneud, mewn iaith blaen. |
function.parameters | object | Y dadleuon fel sgema JSON gyda type: "object" ar y brig. Gweler Allweddeiriau sgema isod. |
Mae gan bob pwynt terfyn ei sillafiad ei hun o offeryn. Anfonwch yr un sy'n perthyn i'r pwynt terfyn rydych yn ei alw:
{
"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
Mae tool_choice yn dweud a gaiff y model, neu a rhaid iddo, alw offeryn. Fe'i darllenir gyda tools yn unig.
| Gwerth | Disgrifiad | Yn cael ei gymhwyso gan |
|---|---|---|
"auto" | Mae'r model yn penderfynu a yw'n ateb mewn testun neu'n galw offeryn. Dyma'r rhagosodiad. | Pob model |
"required" | Mae'r ateb yn galw o leiaf un offeryn. | Modelau pwysau agored a gynhelir |
{"type": "function", "function": {"name": "get_weather"}} | Mae'r ateb yn galw'r ffwythiant hwn. Rhaid i'r enw fod yn un o'r ffwythiannau yn tools. Gadewir galwadau i ffwythiannau eraill allan o'r ateb. | Modelau pwysau agored a gynhelir |
Mae'r modelau Shannon (shannon-*) yn penderfynu ym mhob cais, fel gydag auto.
Gyda required neu ffwythiant a enwir, darllenwch finish_reason cyn i chi ddarllen tool_calls. Pan nad yw'r model yn cynhyrchu galwad, mae'r ateb yn ateb testun gyda finish_reason: "stop".
| Ystyr | /v1/chat/completions | /v1/responses | /v1/messages |
|---|---|---|---|
| Mae'r model yn penderfynu | "auto" | "auto" | {"type": "auto"} |
| Galw o leiaf un offeryn | "required" | "required" | {"type": "any"} |
| Galw un ffwythiant a enwir | {"type": "function", "function": {"name": "get_weather"}} | {"type": "function", "name": "get_weather"} | {"type": "tool", "name": "get_weather"} |
Derbynnir er mwyn cydnawsedd: tool_choice: "none" a parallel_tool_calls. Ar gyfer tro heb alwadau offer, anfonwch y cais heb tools.
Galwadau offer yn yr ateb
| Maes | Math | Disgrifiad |
|---|---|---|
finish_reason | string | tool_calls pan fo'r ateb yn cario o leiaf un alwad. |
message.tool_calls | array | Un cofnod am bob galwad. Mae'r maes yn bresennol dim ond pan ofynnodd y model am alwad. |
tool_calls[].id | string | call_ ac yna 32 nod hecsadegol. Anfonwch ef yn ôl fel tool_call_id gyda'r canlyniad. |
tool_calls[].type | string | Bob amser yn function. |
tool_calls[].function.name | string | Y ffwythiant i'w redeg. |
tool_calls[].function.arguments | string | Y dadleuon fel llinyn JSON, "{}" pan nad oes dim. Dadansoddwch ef cyn ei ddefnyddio. |
message.content | string | null | null pan fo'r ateb yn cynnwys galwadau yn unig. Gall y modelau pwysau agored a gynhelir ddychwelyd testun wrth ymyl y galwadau; mae'r modelau Shannon yn dychwelyd null. |
Yr un alwad ym mhob fformat. Ar /v1/responses mae'n eitem function_call o output, gyda arguments fel llinyn JSON. Ar /v1/messages mae'n floc cynnwys tool_use y mae ei input yn wrthrych JSON, mae ei id yn dechrau gyda toolu_, ac mae stop_reason yn 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"}
}
]
} Sawl galwad mewn un tro
Gall ateb gario sawl galwad. Rhedwch bob un ohonynt ac anfonwch un canlyniad am bob galwad, pob un gyda'i tool_call_id ei hun, yn y cais nesaf.
Mae'r modelau pwysau agored a gynhelir yn dychwelyd pob galwad unigryw unwaith: mae dwy alwad gyda'r un enw a'r un dadleuon yn cyrraedd fel un.
Galwadau offer wedi'u ffrydio
Gyda stream: true, mae galwad yn cyrraedd mewn un darn: mae'r darn yn dal y llinyn arguments cyflawn, felly nid oes darnau i'w huno. Mae index yn cyfrif galwadau'r tro 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
}
]
} | Pwynt terfyn | Beth sy'n cyrraedd |
|---|---|
/v1/chat/completions | Un chat.completion.chunk am bob galwad, gyda'r alwad yn delta.tool_calls[0]. Mae gan y darn olaf finish_reason: "tool_calls" a usage. |
/v1/responses | Am bob galwad: response.output_item.added (eitem function_call gydag arguments gwag), response.function_call_arguments.delta (y llinyn cyfan), response.function_call_arguments.done, response.output_item.done. |
/v1/messages | Am bob galwad: content_block_start (bloc tool_use gydag input gwag), un content_block_delta y mae ei input_json_delta.partial_json yn holl destun y dadleuon, content_block_stop. Yna mae message_delta yn cario stop_reason: "tool_use". |
Ar shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1, mae cais wedi'i ffrydio sy'n cario tools yn cyflwyno testun ei ateb mewn un delta content ar ddiwedd y tro. Ffrydio
Anfon canlyniadau yn ôl
Mae'r ail gais yn ailadrodd y sgwrs ac yn ychwanegu dau beth: tro'r assistant a ofynnodd am y galwadau, ac un canlyniad am bob galwad.
{
"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\"}"
}
]
}
]
} - Anfonwch dro'r assistant yn ôl fel y cawsoch ef, cyn y canlyniadau. Mae pob canlyniad yn cael ei baru â'i alwad gan yr id:
tool_call_idar/v1/chat/completions,call_idar/v1/responses,tool_use_idar/v1/messages. - Testun yw canlyniad. Cyfresolwch wrthrych yn llinyn JSON ar gyfer
content(outputar/v1/responses). Ar/v1/messagesmaecontentbloctool_resultyn llinyn neu'n rhestr o flociau testun. - Yn nhro'r assistant, mae
function.argumentsyn parhau'n llinyn JSON, yn union fel y cyrhaeddodd. - Gall y sgwrs ddod i ben â chanlyniad offeryn. Nid oes angen neges defnyddiwr newydd: mae'r model yn parhau o'r canlyniad.
- Pan fo eich ffwythiant yn methu, anfonwch y methiant fel testun y canlyniad. Yna gall y model ei adrodd neu ofyn am alwad arall.
Allweddeiriau sgema
Sgema JSON yw parameters (input_schema ar /v1/messages). Mae teulu Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) a'r modelau pwysau agored a gynhelir yn ei dderbyn fel yr anfonwch ef.
Mae shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1 yn derbyn yr is-set hon, ar y tri phwynt terfyn:
| Triniaeth | Allweddeiriau |
|---|---|
| Darllenir fel y'i hanfonwyd | Pob allweddair nad yw'n cael ei enwi yn y rhesi isod, er enghraifft type, properties, required, items, enum, description, minimum, maximum, anyOf ac allOf, ar bob lefel o'r sgema. |
format | Darllenir ar gyfer y gwerthoedd int32, int64, float, double, byte, date, date-time ac enum. |
oneOf | Darllenir fel anyOf. |
| Dim yn rhan o'r sgema y mae'r modelau hyn yn ei dderbyn | $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 ac exclusiveMaximum pan fônt yn rhifau; gwerthoedd eraill format. |
Ymddygiad a therfynau
- Nid yw'r API yn gosod uchafswm ar nifer yr offer nac uchafswm ar nifer y rowndiau.
- Gall corff cais fod hyd at 32 MiB, a rhaid i'r sgwrs gyda'i chanlyniadau ffitio ffenestr cyd-destun y model.
- Pan fo cais yn cario
tools, maeshannon-1.6-lite,shannon-1.6-pro,shannon-2-liteashannon-2-proyn defnyddiotemperaturerhagosodedig o 0.2. Anfonwchtemperaturei osod gwerth arall. - Mae pob rownd yn gais ar ei ben ei hun: mae'n tynnu o'ch balans ac yn cyfrif tuag at amddiffyniad rhag llifogydd fel unrhyw gais arall. Terfynau a balans
Gwallau
Ateb arferol gyda statws 200 yw galwad offeryn. Mae'r gwallau hyn yn ymwneud â'r cais ei hun:
| Statws | Math | Neges | Pryd |
|---|---|---|---|
400 | invalid_request_error | unknown model: <id> | Nid yw model yn id yn y rhestr gyhoeddedig. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Nid yw tools yn arae, neu mae gan faes arall y math JSON anghywir. |
413 | invalid_request_error | Failed to buffer the request body: … | Mae corff y cais yn fwy na 32 MiB. Mae'r gwall yn cario code: "request_too_large". |
Y model sy'n ysgrifennu'r dadleuon. Gwiriwch hwy yn erbyn eich sgema cyn i chi redeg y ffwythiant, fel y byddech yn gwirio unrhyw fewnbwn o'r tu allan.
Mae gwallau dilysu, balans a gweinydd yr un fath ag ar gyfer pob cais. Rheoli gwallau