LLM API کے ساتھ قدرتی زبان سے شیل کمانڈ: JSON اور لاگت

ماڈل سے ایک JSON آبجیکٹ طلب کریں جس میں تین فیلڈز ہوں (type, command, explanation)، جواب کو چند سو ٹوکنز تک محدود رکھیں، اور کمانڈ چلانے کے بجائے اسے پرنٹ کریں۔ ٹوکنز کے لحاظ سے، ایسی درخواست زیادہ تر پرامپٹ پر مشتمل ہوتی ہے جس کا جواب مختصر اور متوقع ہوتا ہے: ذیل کے مفروضوں کے تحت، ان میں سے 1,000 کی لاگت DeepSeek-V4-Flash پر $0.012 ہے۔

فرض کریں کہ آپ کسی اندرونی CLI میں "جو چاہیں بیان کریں" والا باکس شامل کر رہے ہیں۔ کوئی شخص میرے ہوم فولڈر میں 100 MB سے بڑی فائلیں تلاش کریں لکھتا ہے، اور آپ چاہتے ہیں کہ ایک ایسی لائن واپس ملے جسے وہ پڑھ، جانچ اور پیسٹ کر سکے۔ اس کے بعد دو سوالات جنم لیتے ہیں: آپ ماڈل کو اندازہ لگانے یا کوئی خطرناک کام کرنے سے کیسے روکیں، اور جب سو لوگ سارا دن اسے استعمال کریں تو اس کی لاگت کیا ہوگی؟

ایک محدود کام: جواب مختصر کیوں ہوتا ہے#

9 نومبر 2026 کو ایک Telegram چینل نے dale-0.8b کے ماڈل کارڈ کو دوبارہ بیان کیا، جو ایک اوپن ماڈل ہے جو بالکل یہی ایک کام کرتا ہے۔ Hugging Face پر ماڈل کارڈ کے مطابق (10 نومبر 2026 کو چیک کیا گیا)، dale-0.8b، Qwen3.5-0.8B کا Apache-2.0 کے تحت مکمل فائن ٹیون ہے جو ہسپانوی یا انگریزی درخواست کو ایک Linux bash کمانڈ میں بدل دیتا ہے۔ مصنف، Manuel García، اپنے ٹیسٹ سیٹ پر 79.4% (471 میں سے 374 کیسز) رپورٹ کرتے ہیں، جبکہ Qwen3.5-9B بیس اور بغیر فائن ٹیوننگ کے Gemma 4 E4B-it کے لیے 62.8% ہے۔ یہ ایک شخص کے ٹیسٹ سیٹ پر خود رپورٹ کردہ اعداد و شمار ہیں، لہٰذا انہیں ایک ڈیٹا پوائنٹ سمجھیں، درجہ بندی نہیں۔

ہمارے لیے مفید چیز کام کی ساخت ہے، ماڈل نہیں۔ کارڈ ایک مقررہ سسٹم پرامپٹ، ایک سیاق و سباق کی لائن (OS، ڈسٹرو، پیکیج مینیجر، ٹولز) کے ساتھ درخواست، سوچ بند، اور 200 ٹوکنز تک محدود جواب بیان کرتا ہے۔ یہ حد لاگت کے دو لیورز میں سے ایک ہے: جب جواب ایک مختصر JSON آبجیکٹ ہو، تو آؤٹ پٹ سائیڈ مختصر اور متوقع ہوتی ہے، کیونکہ حد اسے محدود کرتی ہے۔ دوسرا لیور پرامپٹ ہے۔ بل میں ہر طرف کا حصہ کتنا ہے، نیچے جدول دکھاتا ہے؛ یہ ماڈل سے ماڈل مختلف ہوتا ہے۔

اس کے لیے آپ کو 0.8B ماڈل کی ضرورت نہیں۔ یہی فارمیٹ کسی بھی API ماڈل پر کام کرتا ہے، اور یہی اس مضمون کا باقی حصہ بناتا ہے۔

جواب کا فارمیٹ: کمانڈ، انکار یا غیر یقینی#

تدبیر یہ ہے کہ ماڈل کے پاس ہمیشہ "نہیں" کہنے کا ایک جائز راستہ ہو۔ جواب ایک آبجیکٹ ہے:

{"type": "command | refuse | unsure", "command": "...", "explanation": "..."}

• command: ایک bash کمانڈ، نیز ایک جملے میں وضاحت کہ یہ کیا کرتی ہے۔
• refuse: درخواست تباہ کن ہے یا شیل سے اس کا کوئی تعلق نہیں۔ کوئی کمانڈ نہیں۔
• unsure: درخواست بہت مبہم ہے ("میری ڈسک صاف کرو")۔ وضاحت میں ایک وضاحتی سوال ہوتا ہے۔

unsure کے بغیر، ایک مبہم درخواست اندازہ لگانے پر مجبور کرتی ہے، اور اندازہ لگایا گیا rm وہی ہوتا ہے جو آپ کو یاد رہتا ہے۔ کارڈ کے فارمیٹ میں بھی یہی تین اقسام ہیں؛ ہم خیال دوبارہ استعمال کرتے ہیں، ماڈل نہیں۔

اسکرپٹ#

ایک فائل، openai پیکیج، کلید ایک ماحولیاتی متغیر میں۔ بیس URL اور مکمل ماڈل آئی ڈی CheapTokens ڈاکس سے آتے ہیں؛ مختصر آئی ڈیز قبول نہیں ہوتیں، لہٰذا deepseek-ai/DeepSeek-V4-Flash-0731 استعمال کریں۔

import json
import os
import sys

from openai import OpenAI

client = OpenAI(
    base_url='https://api.cheaptokens.dev/v1',
    api_key=os.environ['CHEAPTOKENS_API_KEY'],
)
MODEL = 'deepseek-ai/DeepSeek-V4-Flash-0731'

SYSTEM = '''You turn a request into ONE Linux bash command.
Reply with a single JSON object and nothing else:
{"type": "command" | "refuse" | "unsure", "command": "<one command, or empty>", "explanation": "<one short sentence>"}
Use "refuse" when the request is destructive or not about the shell.
Use "unsure" when it is too vague, and put a clarifying question in "explanation".'''

CONTEXT = 'os: Ubuntu 24.04; package manager: apt; tools: git, curl, jq'


def parse(text):
    start = text.find('{')
    if start == -1:
        return None
    try:
        obj, _ = json.JSONDecoder().raw_decode(text[start:])
    except json.JSONDecodeError:
        return None
    if not isinstance(obj, dict) or obj.get('type') not in ('command', 'refuse', 'unsure'):
        return None
    return obj


def ask(request):
    resp = client.chat.completions.create(
        model=MODEL,
        max_tokens=200,
        temperature=0,
        messages=[
            {'role': 'system', 'content': SYSTEM},
            {'role': 'user', 'content': f'Context: {CONTEXT}\nRequest: {request}'},
        ],
    )
    return parse(resp.choices[0].message.content), resp.usage


if __name__ == '__main__':
    result, usage = ask(' '.join(sys.argv[1:]))
    if result is None:
        print('Could not read the reply as JSON. Try again.')
    elif result['type'] == 'command':
        print(result['explanation'])
        print('\n    ' + result['command'] + '\n')
        print('Read it, then copy it yourself. This script never runs it.')
    else:
        print(f"[{result['type']}] {result['explanation']}")
    print(f'tokens: {usage.prompt_tokens} in, {usage.completion_tokens} out')

اسے python shellhelp.py find files bigger than 100 MB in my home folder کے طور پر چلائیں۔ یہاں تین انتخاب اہم ہیں:

• کہیں بھی subprocess نہیں۔ کمانڈ اسکرین پر متن ہے۔ اسے چلانا آپ کا فیصلہ ہے، اسے پڑھنے کے بعد۔
• max_tokens=200، کارڈ کی حد کی طرح۔ ایک JSON آبجیکٹ آسانی سے فٹ ہو جاتا ہے؛ بکھرا ہوا جواب 200 ٹوکنز پر کاٹ دیا جاتا ہے بجائے اس کے کہ آپ کے خرچ پر چلتا رہے۔ حد پورے جواب پر لاگو ہوتی ہے، لہٰذا اگر کوئی ماڈل اپنی استدلال لکھے، تو وہ حد کھا سکتا ہے۔ اگر کبھی جواب finish_reason کے ساتھ length کے برابر ختم ہو، تو حد تھوڑی بڑھا دیں۔ اس پر مزید max_tokens کے ساتھ آؤٹ پٹ ٹوکنز کم کرنا میں۔
• فارمیٹ پرامپٹ میں طلب کیا جاتا ہے، پھر احتیاط سے پارس کیا جاتا ہے۔ raw_decode کسی بھی بھٹکی ہوئی کوڈ فینس یا { سے پہلے کے جملے کو نظر انداز کر دیتا ہے۔ اگر آپ مزید آگے جانا چاہیں، تو OpenAI-مطابق API سے درست JSON اور جواب پر json.JSONDecodeError کا حل دیکھیں۔

کچھ بھی چلانے سے پہلے، جانچ لیں کہ مراحل کی ترتیب واضح ہے:

1,000 درخواستوں کی لاگت#

اسکرپٹ کی آخری لائن usage پرنٹ کرتی ہے۔ یہ اصل عدد ہے، اور آپ کو اپنا پڑھنا چاہیے۔ جب تک یہ آپ کے پاس نہ ہو، ایک مفروضے کے ساتھ کام کریں: پرامپٹ تقریباً 400 ان پٹ ٹوکنز بنتا ہے (اسکرپٹ میں ننگا پرامپٹ موٹے اندازے سے تقریباً 150 ٹوکنز ہے؛ باقی تین یا چار مثال درخواست-و-جواب جوڑوں کے لیے گنجائش ہے جو آپ غالباً شامل کریں گے)، اور JSON جواب تقریباً 60 آؤٹ پٹ ٹوکنز۔

1,000 درخواستوں کے لیے یہ 400 × 1,000 = 400,000 ان پٹ ٹوکنز اور 60 × 1,000 = 60,000 آؤٹ پٹ ٹوکنز ہیں۔ جدول کیٹلاگ کے ہر ماڈل کے لیے بالکل یہی قیمت لگاتا ہے، ساتھ میں OpenRouter کالم؛ اعداد و شمار لائیو قیمتوں سے آتے ہیں، لہٰذا وہ تازہ رہتے ہیں۔

مجموعی طور پر، ان پٹ اور آؤٹ پٹ کو ملا کر، اس کام کے بوجھ کے لیے DeepSeek-V4-Flash OpenRouter سے سستا نکلتا ہے۔ ٹوکنز کے لحاظ سے درخواست تقریباً سب ان پٹ ہے اور جواب مختصر ہے، لیکن دونوں طرف بل لگتا ہے، لہٰذا پرامپٹ اور جواب دونوں کو کم کریں۔ فی ماڈل قیمتیں قیمتوں کے صفحے پر ہیں، اور ماڈل خود DeepSeek صفحے پر بیان کیا گیا ہے: 380K سیاق و سباق، 32,768 آؤٹ پٹ ٹوکنز تک، کسی بھی وقت ایک قیمت۔

تناسب محسوس کرنے کا ایک تیز طریقہ:

ماہانہ 100,000 درخواستیں چاہیں؟ 100 سے ضرب دیں: 40,000,000 ان پٹ اور 6,000,000 آؤٹ پٹ ٹوکنز۔ یہی دو اعداد اسی طرح ::cost میں ڈالیں اور قطار پڑھیں۔

اپنی درخواستوں پر جانچیں#

کارڈ کا 79.4% آپ کے پرامپٹ، آپ کے OS یا آپ کے صارفین کے الفاظ کے بارے میں کچھ نہیں کہتا۔ 20 حقیقی درخواستیں ان کمانڈز کے ساتھ لکھیں جو آپ قبول کریں گے اور موازنہ کریں، بالکل چھوٹے eval سیٹ پر پرامپٹ جانچنے کی طرح۔ کچھ ایسی شامل کریں جنہیں اسکرپٹ کو انکار کرنا یا غیر یقینی قرار دینا چاہیے، جیسے "سب کچھ حذف کر دو" یا "میرا کمپیوٹر تیز کرو"۔

جب کچھ غلط ہو، تو علامت عام طور پر حل کی طرف اشارہ کرتی ہے:

• Could not read the reply as JSON: خام متن ایک بار پرنٹ کریں۔ "Sure!" جیسا سابقہ سنبھال لیا جاتا ہے؛ حد سے کٹا جواب نہیں، لہٰذا finish_reason چیک کریں۔
• 401 یا 404: غلط کلید، بیس URL یا ماڈل آئی ڈی۔ فہرست API 401 یا 404: کلید، بیس URL، ماڈل آئی ڈی میں ہے۔
• کمانڈز جو کسی مختلف سسٹم کے مطابق ہوں: سیاق و سباق کی لائن وجہ ہے۔ اسے درست رکھیں (OS، پیکیج مینیجر، ٹولز)؛ یہ چند درجن ٹوکنز لیتی ہے اور Fedora باکس پر غلط apt بچاتی ہے۔

وہی کام، مختلف ماڈل؟ MODEL کو ڈاکس سے GLM یا MiniMax آئی ڈی سے بدلیں، پرامپٹ رکھیں، اور اسکرپٹ کے پرنٹ کردہ ٹوکن شماروں کا اوپر کے جدول سے موازنہ کریں۔