Sruthú
Socraigh stream ar true agus tagann an freagra mar server-sent events fad a scríobhann an múnla é: réasúnaíocht ar dtús, ansin an freagra, ansin blúire deireanach leis an gcúis chríochnaithe agus an úsáid. Úsáid é aon uair a bhíonn duine ag fanacht leis an téacs, agus do fhreagraí fada.
POST https://api.shannon-ai.com/v1/chat/completions
Tugann SDKanna OpenAI na blúirí duit ceann ar cheann. Léigh gach blúire de réir an ruda a iompraíonn sé: píosa réasúnaíochta, píosa den fhreagra, glao uirlise, nó deireadh an fhreagra.
from openai import OpenAI, APIError
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com/v1",
)
stream = client.chat.completions.create(
model="shannon-3",
messages=[{"role": "user", "content": "Explain server-sent events in three sentences."}],
stream=True,
)
answer, reasoning, tool_calls = [], [], []
finish_reason = usage = None
try:
for chunk in stream:
if chunk.usage:
usage = chunk.usage
if not chunk.choices:
continue
choice = chunk.choices[0]
delta = choice.delta
thought = getattr(delta, "reasoning_content", None)
if thought:
reasoning.append(thought)
if delta.content:
answer.append(delta.content)
print(delta.content, end="", flush=True)
for call in delta.tool_calls or []:
tool_calls.append((call.id, call.function.name, call.function.arguments))
if choice.finish_reason:
finish_reason = choice.finish_reason
except APIError as error:
# A failure after the stream started arrives as an error chunk.
print(f"\nstream failed: {error}")
print(f"\n{finish_reason} {usage}") import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
const stream = await client.chat.completions.create({
model: "shannon-3",
messages: [{ role: "user", content: "Explain server-sent events in three sentences." }],
stream: true,
});
let answer = "";
let reasoning = "";
const toolCalls = [];
let finishReason = null;
let usage = null;
try {
for await (const chunk of stream) {
if (chunk.usage) usage = chunk.usage;
const choice = chunk.choices?.[0];
if (!choice) continue;
const delta = choice.delta;
if (delta.reasoning_content) reasoning += delta.reasoning_content;
if (delta.content) {
answer += delta.content;
process.stdout.write(delta.content);
}
for (const call of delta.tool_calls ?? []) {
toolCalls.push({ id: call.id, name: call.function.name, arguments: call.function.arguments });
}
if (choice.finish_reason) finishReason = choice.finish_reason;
}
} catch (error) {
// A failure after the stream started arrives as an error chunk.
console.error("\nstream failed:", error.message);
}
console.log("\n", finishReason, usage); curl -N https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"messages": [{"role": "user", "content": "Explain server-sent events in three sentences."}],
"stream": true
}' Conas a fhrámaítear sruth
- Tá stádas
200ar an bhfreagra agus na ceanntáscacontent-type: text/event-streamaguscache-control: no-cache. - Is líne amháin é gach imeacht a thosaíonn le
data:agus a leanann líne fholamh. Is blúire JSON amháin é an téacs i ndiaidhdata:. Níl aon línteevent:náid:ann. - Is nóta tráchta é líne a thosaíonn le camóg, mar
: ping, a choinníonn an nasc oscailte. Scipeáil é. - Críochnaíonn an sruth le
data: [DONE]. Is sruth neamhiomlán é sruth a stopann gan é.
Blúirí in ord
Is réad chat.completion.chunk é gach blúire:
{
"id": "chatcmpl-5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
"object": "chat.completion.chunk",
"created": 1791625200,
"model": "shannon-3",
"choices": [
{
"index": 0,
"delta": {
"content": "Server-sent"
},
"finish_reason": null
}
]
} Iompraíonn gach blúire d'aon sruth amháin an id, created agus model céanna. Coinníonn choices iontráil amháin i gcónaí. Coinníonn a delta an rud atá nua, agus is null é finish_reason go dtí an blúire deireanach.
| Eochair i delta | Cineál | Tuairisc | Seolta ag |
|---|---|---|---|
role | string | assistant i gcónaí. Tagann sé uair amháin, ag tús an tsrutha. | Múnlaí open-weight óstáilte, shannon-2-lite, shannon-2-pro |
reasoning_content | string | Píosa de réasúnaíocht an mhúnla. Ceangail na píosaí in ord. | Múnlaí open-weight óstáilte, teaghlach Shannon 3, shannon-1.6-pro, shannon-coder-1 |
content | string | Píosa den fhreagra. Ceangail na píosaí in ord. | Gach múnla |
tool_calls | array | Glao uirlise iomlán amháin. Féach Deilteanna glaonna uirlisí. | Gach múnla |
Tagann an réasúnaíocht ar dtús, ansin an freagra, ansin aon ghlaonna uirlisí. Léigh blúire de réir na n-eochracha ina delta, ní de réir a áite sa sruth: is féidir le delta role a choinneáil in éineacht leis an gcéad phíosa téacs, agus bíonn an ceann deireanach folamh.
Sruth iomlán mar a thaistealaíonn sé. Chun na línte a choinneáil gearr, fágtar id, object, created agus model ar lár i ngach blúire anseo.
data: {"choices":[{"index":0,"delta":{"reasoning_content":"Three sentences:"},"finish_reason":null}]}
data: {"choices":[{"index":0,"delta":{"reasoning_content":" what it is, how it is framed, why it is used."},"finish_reason":null}]}
: ping
data: {"choices":[{"index":0,"delta":{"content":"Server-sent"},"finish_reason":null}]}
data: {"choices":[{"index":0,"delta":{"content":" events let a server push text to a client over one HTTP reply."},"finish_reason":null}]}
data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":1190,"completion_tokens":84,"total_tokens":1274}}
data: [DONE] Deilteanna réasúnaíochta
Seolann múnla a dhéanann réasúnaíocht a réasúnaíocht i delta.reasoning_content roimh an bhfreagra. Coinnigh an dá théacs scartha: taispeáin an réasúnaíocht mar chuid ar leith ar féidir í a fhilleadh, nó fág ar lár í.
Ní sheolann na múnlaí open-weight óstáilte aon réasúnaíocht nuair is off é reasoning_effort, ná nuair a bhíonn response_format ar an iarratas.
Déanann shannon-2-lite agus shannon-2-pro réasúnaíocht sula bhfreagraíonn siad freisin. Ar an gcríochphointe seo seolann siad línte nótaí tráchta : thinking fad a dhéanann siad sin, agus ansin an freagra.
Níl reasoning_content sna múnlaí clóscríofa de SDKanna OpenAI. In Python léigh é le getattr(delta, "reasoning_content", None); in JavaScript oibríonn delta.reasoning_content mar atá.
Deilteanna glaonna uirlisí
Tagann glao uirlise ina iomláine: blúire amháin do gach glao, a gcoinníonn a delta an glao leis an sreang arguments iomlán. Uimhríonn index glaonna an fhreagra ó 0. Oibríonn cód a cheanglaíonn arguments píosa ar phíosa gan athrú, mar ceanglaíonn sé píosa amháin.
{
"tool_calls": [
{
"index": 0,
"id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
}
}
]
} Tar éis na nglaonna, tá finish_reason tool_calls ar an mblúire deireanach.
Nuair a bhíonn tools ar an iarratas, seolann shannon-1.6-lite, shannon-1.6-pro agus shannon-coder-1 téacs an fhreagra mar delta amháin ag deireadh an fhreagra.
An blúire deireanach
Tá delta folamh sa bhlúire deireanach roimh data: [DONE], agus finish_reason agus usage an iarratais, uile sa bhlúire chéanna. Tá sé i ngach sruth; níl stream_options ag teastáil uait.
{
"id": "chatcmpl-5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
"object": "chat.completion.chunk",
"created": 1791625200,
"model": "shannon-3",
"choices": [
{
"index": 0,
"delta": {},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1190,
"completion_tokens": 84,
"total_tokens": 1274
}
} Ar na múnlaí open-weight óstáilte tá prompt_tokens_details.cached_tokens agus completion_tokens_details.reasoning_tokens ag usage freisin.
Tar éis iarratais a bhfuil web_search: true air agus gur aimsigh a chuardach rud éigin, iompraíonn an bhlúire dheireanach sources freisin, agus iompraíonn blúire amháin roimpi na marcóirí luaite mar delta.annotations. Insuite i Cuardach Gréasáin
| finish_reason | Tuairisc | Seolta ag |
|---|---|---|
stop | Chríochnaigh an múnla a fhreagra, nó tháinig sreang stop chun solais. | Gach múnla |
tool_calls | Tá glao uirlise amháin nó níos mó sa fhreagra. | Gach múnla |
length | Gearradh an freagra ag an teorainn aschuir. | Teaghlach Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
Déantar cur síos ar réimsí usage leis an gcríochphointe. Chat Completions
Línte keep-alive
Fad a bhíonn an múnla ag obair agus nach bhfuil faic le seoladh aige fós, iompraíonn an sruth línte nótaí tráchta. Níl aon sonraí iontu. Scipeálann parsálaí SSE iad leis féin; caithfidh cód a léann línte amh gach líne a thosaíonn le camóg a scipeáil.
| Líne | Seolta ag | Cathain |
|---|---|---|
: ping | Teaghlach Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | Gach 15 soicind. |
: keepalive | Múnlaí open-weight óstáilte | Gach 15 soicind fad a bhíonn an múnla ag obair. |
: thinking | shannon-2-lite, shannon-2-pro | Fad a dhéanann an múnla réasúnaíocht. |
Earráidí laistigh de shruth
Nuair a thosaíonn sruth is 200 a stádas, mar sin tagann teip taobh istigh den sruth: blúire le ball error san áit a mbeadh choices.
data: {"error":{"message":"The model backend failed to answer. Please retry.","type":"api_error","code":null,"param":null}}
data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":1190,"completion_tokens":12,"total_tokens":1202}}
data: [DONE] Tar éis an bhlúire earráide leanann an blúire deireanach, le finish_reason agus usage, agus data: [DONE] fós. Seiceáil gach blúire le haghaidh error. Gan an tseiceáil sin tá cuma iomlán ar fhreagra a theip leath bealaigh.
| Cineál | Cód | Teachtaireacht | Cathain |
|---|---|---|---|
api_error | The model backend failed to answer. Please retry. | Theip ar an múnla, nó níor scríobh sé faic. Seol an t-iarratas arís. | |
rate_limit_error | Shannon routes are temporarily busy. Please retry. | Tá an múnla gnóthach faoi láthair. Fan cúpla soicind agus seol an t-iarratas arís. | |
invalid_request_error | context_length_exceeded | Tá an comhrá níos faide ná fuinneog comhthéacs an mhúnla. Giorraigh é sula seolann tú arís é. Athraíonn téacs na teachtaireachta. |
Seolann na múnlaí open-weight óstáilte an ball error le type agus message amháin.
Ardaíonn SDKanna Python agus JavaScript OpenAI blúire earráide mar earráid API agus tú ag iterál, mar sin cuir do ghnáthláimhseáil earráidí timpeall na lúibe.
Tá leathanach dá gcuid féin ag cóid stádais, corp na hearráide agus cad atá le hathiarraidh. Láimhseáil Earráide
An nasc a dhúnadh
Cuireann dúnadh an naisc stop leis an seachadadh, ní leis an iarratas. Scríobhann an múnla an freagra go dtí a dheireadh agus muirearaítear an t-iarratas amhail is dá mbeadh sé léite agat go léir. Chun níos lú a íoc, iarr níos lú: socraigh max_tokens níos ísle ar mhúnla a chuireann i bhfeidhm é.
Is féidir le sruth deireadh a chur go luath ar a bhealach chugat freisin, mar shampla ar bhriseadh líonra nó fad a nuashonraítear freastalaí. Stopann sé ansin gan an blúire deireanach agus gan data: [DONE]. Déileáil leis an bhfreagra sin mar fhreagra neamhiomlán agus seol an t-iarratas arís.
Sruth a léamh gan SDK
Déanann léitheoir ceart cúig rud: seolann sé earráidí a thagann roimh an sruth chuig a láimhseáil earráidí, roinneann sé an corp ina línte, scipeálann sé línte nótaí tráchta, stopann sé ag data: [DONE], agus seiceálann sé gach blúire le haghaidh error.
import json
import requests
response = requests.post(
"https://api.shannon-ai.com/v1/chat/completions",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"model": "shannon-3",
"messages": [{"role": "user", "content": "Explain server-sent events in three sentences."}],
"stream": True,
},
stream=True,
)
# 1. Errors before the stream are plain JSON with their own status.
if response.status_code != 200:
raise RuntimeError(f"{response.status_code}: {response.text}")
answer, done = [], False
for raw in response.iter_lines(): # 2. one line at a time
line = raw.decode("utf-8")
if not line.startswith("data: "): # 3. empty lines and ": ping" comments
continue
data = line[len("data: "):]
if data == "[DONE]": # 4. the end of the stream
done = True
break
chunk = json.loads(data)
if "error" in chunk: # 5. a failure inside the stream
raise RuntimeError(chunk["error"]["message"])
delta = chunk["choices"][0]["delta"]
if delta.get("content"):
answer.append(delta["content"])
if chunk.get("usage"):
print(chunk["choices"][0]["finish_reason"], chunk["usage"])
if not done:
raise RuntimeError("the stream ended before [DONE]")
print("".join(answer)) const response = await fetch("https://api.shannon-ai.com/v1/chat/completions", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "shannon-3",
messages: [{ role: "user", content: "Explain server-sent events in three sentences." }],
stream: true,
}),
});
// 1. Errors before the stream are plain JSON with their own status.
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const decoder = new TextDecoder();
let buffer = "";
let answer = "";
let done = false;
read: for await (const bytes of response.body) {
buffer += decoder.decode(bytes, { stream: true });
const lines = buffer.split("\n"); // 2. one line at a time
buffer = lines.pop(); // keep the unfinished line
for (const line of lines) {
if (!line.startsWith("data: ")) continue; // 3. empty lines and ": ping" comments
const data = line.slice(6);
if (data === "[DONE]") { // 4. the end of the stream
done = true;
break read;
}
const chunk = JSON.parse(data);
if (chunk.error) throw new Error(chunk.error.message); // 5. a failure inside the stream
const choice = chunk.choices[0];
if (choice.delta.content) answer += choice.delta.content;
if (chunk.usage) console.log(choice.finish_reason, chunk.usage);
}
}
if (!done) throw new Error("the stream ended before [DONE]");
console.log(answer); Úsáideann an sampla Python an pacáiste requests. Ritheann an sampla JavaScript ar Node.js 18 nó níos déanaí.
Sruthanna na bhformáidí eile
Sruthaíonn na críochphointí Responses agus Messages freisin. Tá líne event: le hainm an imeachta agus líne data: lena JSON ina bhfrámaí. Liostaíonn gach leathanach a himeachtaí in ord.
| Sa sruth | Chat Completions | Responses | Messages |
|---|---|---|---|
| Frámaí | Línte data: | Línte event: agus data: | Línte event: agus data: |
| Tagann réasúnaíocht i | delta.reasoning_content | response.reasoning_summary_text.delta | thinking_delta |
| Tagann téacs an fhreagra i | delta.content | response.output_text.delta | text_delta |
| Tagann úsáid i | An blúire deireanach | response.completed | message_delta |
| Críochnaíonn an sruth le | An blúire deireanach, ansin data: [DONE] | response.completed | message_stop |