Fara í efni
Streymi

Streymi

Stilltu stream á true og svarið berst sem server-sent events meðan líkanið skrifar það: rökhugsun fyrst, síðan svarið, síðan síðasti búturinn með lokaástæðunni og notkuninni. Notaðu það alltaf þegar manneskja bíður eftir textanum, og fyrir löng svör.

POST https://api.shannon-ai.com/v1/chat/completions

OpenAI SDK gefa þér bútana einn í einu. Lestu hvern bút eftir því sem hann ber: bút af rökhugsun, bút af svari, tólakall eða lok svarsins.

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}")

Hvernig streymi er rammað

  • Svarið hefur stöðuna 200 og hausana content-type: text/event-stream og cache-control: no-cache.
  • Hver atburður er ein lína sem byrjar á data: og á eftir fylgir tóm lína. Textinn á eftir data: er einn JSON-bútur. Engar event: eða id: línur eru til staðar.
  • Lína sem byrjar á tvípunkti, eins og : ping, er athugasemd sem heldur tengingunni opinni. Slepptu henni.
  • Streyminu lýkur með data: [DONE]. Streymi sem stöðvast án þess er ófullkomið.

Bútar í réttri röð

Hver bútur er chat.completion.chunk hlutur:

JSON
{
  "id": "chatcmpl-5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "chat.completion.chunk",
  "created": 1791625200,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Server-sent"
      },
      "finish_reason": null
    }
  ]
}

Allir bútar eins streymis bera sama id, created og model. choices geymir alltaf eina færslu. delta hennar geymir það sem er nýtt, og finish_reason er null fram að síðasta bútnum.

Lykill í delta Gerð Lýsing Sent af
role string Alltaf assistant. Það berst einu sinni, í upphafi streymisins. Hýst líkön með opnum þyngdum, shannon-2-lite, shannon-2-pro
reasoning_content string Bútur af rökhugsun líkansins. Sameinaðu bútana í réttri röð. Hýst líkön með opnum þyngdum, Shannon 3 fjölskyldan, shannon-1.6-pro, shannon-coder-1
content string Bútur af svarinu. Sameinaðu bútana í réttri röð. Öll líkön
tool_calls array Eitt heilt tólakall. Sjá Tool call deltas. Öll líkön

Rökhugsun kemur fyrst, síðan svarið, síðan öll tólakall. Lestu búta eftir lyklunum í delta, ekki eftir stöðu þeirra í streyminu: delta getur geymt role ásamt fyrsta textabútnum, og sá síðasti er tómur.

Heilt streymi eins og það berst. Til að halda línunum stuttum eru id, object, created og model sleppt úr hverjum bút hér.

200 text/event-stream
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]

Rökhugsunar-delta

Líkan sem rökhugsar sendir rökhugsun sína í delta.reasoning_content á undan svarinu. Haltu textunum tveimur aðskildum: sýndu rökhugsunina sem sérstakan hluta sem hægt er að fella saman, eða slepptu henni.

Hýstu líkönin með opnum þyngdum senda enga rökhugsun þegar reasoning_effort er off, og enga þegar beiðnin hefur response_format.

shannon-2-lite og shannon-2-pro rökhugsa líka áður en þau svara. Á þessum endapunkti senda þau : thinking athugasemdarlínur meðan þau gera það, og síðan svarið.

reasoning_content er ekki í tegunduðu líkönum OpenAI SDK. Í Python skaltu lesa það með getattr(delta, "reasoning_content", None); í JavaScript virkar delta.reasoning_content óbreytt.

Tólakalla-delta

Tólakall berst heilt: einn bútur á hvert kall, þar sem delta geymir kallið með heilum arguments streng. index númerar köll svarsins frá 0. Kóði sem sameinar arguments bút fyrir bút virkar óbreyttur, því hann sameinar einn bút.

delta
{
  "tool_calls": [
    {
      "index": 0,
      "id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"city\":\"Paris\"}"
      }
    }
  ]
}

Eftir köllin hefur síðasti búturinn finish_reason tool_calls.

Þegar beiðnin hefur tools senda shannon-1.6-lite, shannon-1.6-pro og shannon-coder-1 svartextann sem eitt delta í lok svarsins.

Síðasti búturinn

Síðasti búturinn á undan data: [DONE] hefur tómt delta, finish_reason og usage beiðninnar, allt í sama bútnum. Hvert streymi hefur hann; þú þarft ekki stream_options.

JSON
{
  "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
  }
}

Hjá hýstu líkönunum með opnum þyngdum hefur usage einnig prompt_tokens_details.cached_tokens og completion_tokens_details.reasoning_tokens.

Eftir beiðni með web_search: true þar sem leitin fann eitthvað ber síðasti búturinn einnig sources, og bútur á undan honum ber tilvísunarmerkin sem delta.annotations. Vefleit

finish_reason Lýsing Sent af
stop Líkanið lauk svari sínu, eða stop strengur birtist. Öll líkön
tool_calls Svarið inniheldur eitt eða fleiri tólakall. Öll líkön
length Svarið var skorið við úttakshámarkið. Shannon 3 fjölskyldan, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1

Reitir usage eru lýstir með endapunktinum. Chat Completions

Keep-alive línur

Meðan líkanið vinnur og hefur enn ekkert að senda ber streymið athugasemdarlínur. Þær geyma engin gögn. SSE-þáttari sleppir þeim sjálfur; kóði sem les hráar línur verður að sleppa hverri línu sem byrjar á tvípunkti.

Lína Sent af Hvenær
: ping Shannon 3 fjölskyldan, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Á 15 sekúndna fresti.
: keepalive Hýst líkön með opnum þyngdum Á 15 sekúndna fresti meðan líkanið vinnur.
: thinking shannon-2-lite, shannon-2-pro Meðan líkanið rökhugsar.

Villur inni í streymi

Þegar streymi er hafið er staða þess 200, svo bilun berst inni í streyminu: bútur með error meðlim þar sem choices væri annars.

200 text/event-stream
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]

Á eftir villubútnum fylgja samt síðasti búturinn, með finish_reason og usage, og data: [DONE]. Athugaðu hvern bút með tilliti til error. Án þeirrar athugunar lítur svar sem mistókst á miðri leið út fyrir að vera fullbúið.

Gerð Kóði Skilaboð Hvenær
api_error The model backend failed to answer. Please retry. Líkanið brást, eða skrifaði ekkert. Sendu beiðnina aftur.
rate_limit_error Shannon routes are temporarily busy. Please retry. Líkanið er upptekið í augnablikinu. Bíddu í nokkrar sekúndur og sendu beiðnina aftur.
invalid_request_error context_length_exceeded Samtalið er lengra en samhengisgluggi líkansins. Styttu það áður en þú sendir það aftur. Texti skilaboðanna er breytilegur.

Hýstu líkönin með opnum þyngdum senda error meðliminn aðeins með type og message.

OpenAI Python og JavaScript SDK varpa villubút sem API-villu meðan þú ítrekar, svo vefðu lykkjuna í venjulega villumeðhöndlun þína.

Stöðukóðar, villumeginmálið og hvað á að reyna aftur eru á sinni eigin síðu. Villumeðhöndlun

Tengingunni lokað

Að loka tengingunni stöðvar afhendinguna, ekki beiðnina. Líkanið skrifar svarið til enda og beiðnin er gjaldfærð eins og þú hefðir lesið allt. Til að borga minna skaltu biðja um minna: stilltu lægra max_tokens á líkani sem tekur tillit til þess.

Streymi getur líka endað snemma á leið til þín, til dæmis við netrof eða meðan verið er að uppfæra netþjón. Þá stöðvast það án síðasta bútsins og án data: [DONE]. Líttu á það svar sem ófullkomið og sendu beiðnina aftur.

Streymi lesið án SDK

Réttur lesari gerir fimm hluti: hann sendir villur sem berast áður en streymið hefst í villumeðhöndlun sína, skiptir meginmálinu í línur, sleppir athugasemdarlínum, stöðvast við data: [DONE] og athugar hvern bút með tilliti til 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))

Python-dæmið notar requests pakkann. JavaScript-dæmið keyrir á Node.js 18 eða nýrra.

Streymi hinna sniðanna

Responses og Messages endapunktarnir streyma líka. Rammar þeirra bera event: línu með nafni atburðarins og data: línu með JSON hans. Hver síða telur atburði sína upp í réttri röð.

Í streyminu Chat CompletionsResponsesMessages
Rammar data: línurevent: og data: línurevent: og data: línur
Rökhugsun berst í delta.reasoning_contentresponse.reasoning_summary_text.deltathinking_delta
Svartexti berst í delta.contentresponse.output_text.deltatext_delta
Notkun berst í Síðasti búturinnresponse.completedmessage_delta
Streyminu lýkur með Síðasti búturinn, síðan data: [DONE]response.completedmessage_stop