بلاگ پر واپس جائیں

API اور SDKگائیڈ

Python میں اسٹریمنگ جوابات

سرکاری openai پیکیج کے ساتھ ماڈل کا جواب اس کے بننے کے ساتھ پرنٹ کریں — سنک اور ایسنک مثالیں، استدلالی آؤٹ پٹ، ٹوکن استعمال اور غلطیوں کا انتظام۔

از CheapTokens Teamشائع شدہ 3 منٹ کا مطالعہ

Python کوڈ جس میں اسٹریم چنکس پر for لوپ اور متن ٹوکن بہ ٹوکن ظاہر ہو رہا ہے
اس صفحہ پر
  1. سیٹ اپ
  2. کم سے کم مثال
  3. استدلالی ماڈلز
  4. ٹوکن استعمال
  5. asyncio
  6. جلد روکنا اور ٹائم آؤٹ
  7. غلطیاں
  8. وائر پر کیا ہے

اسٹریمنگ کے ساتھ، جواب ٹکڑوں میں آتا ہے جبکہ ماڈل ابھی اسے بنا رہا ہوتا ہے، لہٰذا آپ کے صارفین پورے جواب کا انتظار کرنے کے بجائے فوراً متن دیکھتے ہیں۔ API معیاری OpenAI اسٹریمنگ فارمیٹ (سرور-سینٹ ایونٹس) استعمال کرتی ہے، اور سرکاری openai Python پیکیج اسے آپ کے لیے سنبھالتا ہے۔

نیچے دیا گیا ہر مثال مکمل ہے: اسے ایک فائل میں کاپی کریں اور چلائیں۔ مثالیں Python 3.10.12 اور openai 3.31.0 کے ساتھ ایک مقامی ٹیسٹ سرور کے خلاف جانچی گئی ہیں جو API کے اسٹریمنگ فارمیٹ کو دوبارہ پیش کرتا ہے (نحو اور عمل درآمد)۔

سیٹ اپ#

bash
pip install openai
export CHEAPTOKENS_API_KEY="paste-your-key-here"

کم سے کم مثال#

python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

stream = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Write a haiku about latency"}],
    stream=True,
)
for chunk in stream:
    if not chunk.choices:  # service chunk without text, e.g. the final usage chunk
        continue
    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)
print()

دو تفصیلات اہم ہیں:

  • choices کے بغیر چنکس کو چھوڑ دیں۔ کچھ چنکس میں کوئی متن نہیں ہوتا — مثلاً ٹوکن استعمال کے ساتھ آخری چنک۔
  • delta.content خالی ہو سکتا ہے۔ پہلا چنک اکثر صرف رول رکھتا ہے، اور آخری صرف finish_reason۔ متن صرف اس وقت پرنٹ کریں جب وہ موجود ہو۔

استدلالی ماڈلز#

zai-org/GLM-5.3-Flash جواب دینے سے پہلے استدلال کرتا ہے۔ استدلال ڈیلٹا کے ایک الگ فیلڈ میں آتا ہے، reasoning_content، اور جواب خود content میں۔ SDK نامعلوم فیلڈز رکھتا ہے، لہٰذا آپ اسے getattr کے ساتھ پڑھ سکتے ہیں۔ یہ اپنے کلائنٹ اور اپنی اسٹریم کے ساتھ ایک مکمل مثال ہے:

python
import os
import sys
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

stream = client.chat.completions.create(
    model="zai-org/GLM-5.3-Flash",
    messages=[{"role": "user", "content": "Is 1013 a prime number?"}],
    stream=True,
)
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    thinking = getattr(delta, "reasoning_content", None)
    if thinking:
        print(thinking, end="", flush=True, file=sys.stderr)  # reasoning → stderr
    if delta.content:
        print(delta.content, end="", flush=True)              # answer → stdout
print()

جواب کا پہلا لفظ ظاہر ہونے سے پہلے استدلال میں کچھ وقت لگ سکتا ہے — اسٹریم کرنے کی ایک اور وجہ۔

ٹوکن استعمال#

stream_options کے ساتھ استعمال طلب کریں؛ یہ آخری چنک میں آتا ہے، جس میں choices نہیں ہوتا:

python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

stream = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Explain idempotency in one paragraph"}],
    stream=True,
    stream_options={"include_usage": True},
)
usage = None
for chunk in stream:
    if chunk.usage:
        usage = chunk.usage
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

if usage:
    print(f"\ninput: {usage.prompt_tokens}, output: {usage.completion_tokens}")

درخواست کی لاگت حاصل کرنے کے لیے ان نمبروں کو ماڈل کی شرحوں سے ضرب دیں — دیکھیں How to estimate the cost of an AI agent۔

asyncio#

ایسنک کوڈ میں AsyncOpenAI اور async for استعمال کریں۔ کلائنٹ کا اپنا نام ہے، async_client، تاکہ یہ دوسری مثالوں کے سنکرونس client سے ٹکرائے نہیں:

python
import asyncio
import os
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

async def main() -> None:
    stream = await async_client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V4-Flash-0731",
        messages=[{"role": "user", "content": "Name three uses of a message queue"}],
        stream=True,
    )
    async for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
    print()

asyncio.run(main())

جلد روکنا اور ٹائم آؤٹ#

جنریشن روکنے کے لیے لوپ چھوڑ دیں۔ with کے ساتھ اسٹریم کھولنے سے بلاک ختم ہونے پر کنکشن بند ہو جاتا ہے۔ کلائنٹ ٹائم آؤٹ واضح طور پر سیٹ کیا گیا ہے؛ SDK کچھ ناکام درخواستوں کو خود بھی دوبارہ کوشش کرتا ہے (max_retries، ڈیفالٹ میں 2)۔

python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
    timeout=120,  # seconds; long answers take time
)

received = ""
with client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Write a long story about a lighthouse"}],
    stream=True,
) as stream:
    for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            received += chunk.choices[0].delta.content
        if len(received) > 300:  # stop early: enough text received
            break
print(received)

غلطیاں#

پہلے چنک سے پہلے ہونے والی غلطیاں — غلط کلید، خالی بیلنس، نامعلوم ماڈل — اسٹریم بناتے وقت استثنیٰ کے طور پر اٹھائی جاتی ہیں:

python
import os
import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

try:
    stream = client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V4-Flash-0731",
        messages=[{"role": "user", "content": "Hello"}],
        stream=True,
    )
    for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
    print()
except openai.AuthenticationError:          # 401: wrong or rotated key
    print("Check the API key")
except openai.BadRequestError as e:         # 400: e.g. unknown model ID
    print("Bad request:", e.message)
except openai.APIStatusError as e:          # other statuses, e.g. 402 when the balance is used up
    print(e.status_code, e.message)

اسٹیٹس کوڈز اور حل کی مکمل فہرست Common connection errors and how to fix them میں ہے۔

وائر پر کیا ہے#

ڈیبگ کرنے کے لیے، curl کے ساتھ خام اسٹریم دیکھیں (-N بفرنگ بند کر دیتا ہے):

bash
curl -N https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "stream": true,
       "messages": [{"role": "user", "content": "Hi"}]}'

ہر ایونٹ ایک data: {…} لائن ہوتا ہے جس میں JSON چنک ہوتا ہے؛ اسٹریم data: [DONE] کے ساتھ ختم ہوتا ہے۔ کولن سے شروع ہونے والی لائنیں طویل وقفوں کے دوران بھیجے گئے کیپ-الائیو کمنٹس ہیں — کلائنٹس انہیں نظر انداز کرتے ہیں۔