استخدام Qiskit Code Assistant في الوضع المحلي

تعلّم كيفية تثبيت وإعداد واستخدام أيٍّ من نماذج Qiskit Code Assistant على جهازك المحلي.

ملاحظات

• Qiskit Code Assistant في مرحلة الإصدار التجريبي وقد يتغير.
• إذا كان لديك ملاحظات أو أردت التواصل مع فريق التطوير، استخدم قناة Qiskit على Slack أو مستودعات GitHub العامة ذات الصلة.

البدء السريع (موصى به)

أسهل طريقة للبدء مع Qiskit Code Assistant في الوضع المحلي هي استخدام سكريبتات الإعداد التلقائي الخاصة بإضافة VS Code أو JupyterLab. تقوم هذه السكريبتات تلقائيًا بتثبيت Ollama لتشغيل نماذج LLM، وتنزيل النموذج الموصى به، وإعداد الإضافة نيابةً عنك.

إعداد إضافة VS Code

شغّل الأمر التالي في طرفيتك:

bash <(curl -fsSL https://raw.githubusercontent.com/Qiskit/qiskit-code-assistant-vscode/main/setup_local.sh)

يُنفّذ هذا السكريبت الخطوات التالية:

• تثبيت Ollama (إذا لم يكن مثبّتًا مسبقًا)
• تنزيل نموذج Qiskit Code Assistant الموصى به وإعداده
• تهيئة إضافة VS Code للعمل مع نشرك المحلي

إعداد إضافة JupyterLab

شغّل الأمر التالي في طرفيتك:

bash <(curl -fsSL https://raw.githubusercontent.com/Qiskit/qiskit-code-assistant-jupyterlab/main/setup_local.sh)

سيقوم هذا السكريبت بـ:

• تثبيت Ollama (إذا لم يكن مثبّتًا مسبقًا)
• تنزيل نموذج Qiskit Code Assistant الموصى به وإعداده
• تهيئة إضافة JupyterLab للعمل مع نشرك المحلي

النماذج المتاحة

النماذج الحالية

هذه هي أحدث النماذج الموصى باستخدامها مع Qiskit Code Assistant:

1. Qiskit/mistral-small-3.2-24b-qiskit - صدر في أكتوبر 2025
2. qiskit/qwen2.5-coder-14b-qiskit - صدر في يونيو 2025
3. qiskit/granite-3.3-8b-qiskit - صدر في يونيو 2025
4. qiskit/granite-3.2-8b-qiskit - صدر في يونيو 2025

نماذج GGUF (موصى بها للبيئات الشخصية/أجهزة اللابتوب)

نماذج بصيغة GGUF مُحسَّنة للاستخدام المحلي وتتطلب موارد حوسبة أقل:

1. mistral-small-3.2-24b-qiskit-GGUF – صدر في أكتوبر 2025 تم تدريبه على بيانات Qiskit حتى الإصدار 2.1

2. qiskit/qwen2.5-coder-14b-qiskit-GGUF – صدر في يونيو 2025 تم تدريبه على بيانات Qiskit حتى الإصدار 2.0

3. qiskit/granite-3.3-8b-qiskit-GGUF – صدر في يونيو 2025 تم تدريبه على بيانات Qiskit حتى الإصدار 2.0

4. qiskit/granite-3.2-8b-qiskit-GGUF – صدر في يونيو 2025 تم تدريبه على بيانات Qiskit حتى الإصدار 2.0

نماذج Qiskit Code Assistant مفتوحة المصدر متاحة بصيغة safetensors أو GGUF file format ويمكن تنزيلها من Hugging Face كما هو موضح أدناه.

إصدارات Qiskit المستخدمة في التدريب

النموذج						مقاييس الأداء					تاريخ الإصدار	إصدار Qiskit المستخدم في التدريب
	QiskitHumanEval-Hard	QiskitHumanEval	HumanEval	ASDiv	MathQA	SciQ	MBPP	IFEval	CrowsPairs (English)	TruthfulQA (MC1 acc)
mistral-small-3.2-24b-qiskit	32.45	47.02	77.49	3.77	49.68	97.50	64.00	48.44	67.08	39.41	يناير 2026	2.2
qwen2.5-coder-14b-qiskit	25.17	49.01	91.46	4.21	53.90	97.00	77.60	49.64	65.18	37.82	يونيو 2025	2.0
granite-3.3-8b-qiskit	14.57	27.15	62.80	0.48	38.66	93.30	52.40	59.71	59.75	39.05	يونيو 2025	2.0
granite-3.2-8b-qiskit	9.93	24.50	57.32	0.09	41.41	96.30	51.80	60.79	66.79	40.51	يونيو 2025	2.0
granite-8b-qiskit-rc-0.10	15.89	38.41	59.76	—	—	—	—	—	—	—	فبراير 2025	1.3
granite-8b-qiskit	17.88	44.37	53.66	—	—	—	—	—	—	—	نوفمبر 2024	1.2

ملاحظة: جميع النماذج المدرجة في جدول الأداء تم تقييمها باستخدام prompt النظام الخاص بكل منها، المُعرَّف في صفحة النموذج على Hugging Face.

النماذج المتوقفة

هذه النماذج لم تعد تحظى بصيانة نشطة لكنها لا تزال متاحة:

1. qiskit/granite-8b-qiskit-rc-0.10 - صدر في فبراير 2025 (متوقف)
2. qiskit/granite-8b-qiskit - صدر في نوفمبر 2024 (متوقف)

الإعداد المتقدم

إذا كنت تفضّل الإعداد اليدوي أو تحتاج إلى تحكم أكبر في عملية التثبيت، وسّع الأقسام أدناه.

التنزيل من موقع Hugging Face

اتبع هذه الخطوات لتنزيل أي نموذج متعلق بـ Qiskit Code Assistant من موقع Hugging Face:

1. انتقل إلى صفحة نموذج Qiskit المطلوب على Hugging Face.
2. اذهب إلى تبويب Files and Versions ونزّل ملفات النموذج بصيغة safetensors أو GGUF.

التنزيل باستخدام Hugging Face CLI

لتنزيل أي من نماذج Qiskit Code Assistant المتاحة باستخدام Hugging Face CLI، اتبع هذه الخطوات:

1. ثبّت Hugging Face CLI

2. سجّل الدخول إلى حساب Hugging Face الخاص بك

   huggingface-cli login

3. نزّل النموذج الذي تفضّله من القائمة السابقة

   huggingface-cli download <HF REPO NAME> <MODEL PATH> --local-dir <LOCAL PATH>

نشر نماذج Qiskit Code Assistant يدويًا محليًا عبر Ollama

هناك عدة طرق لنشر نموذج Qiskit Code Assistant الذي نزّلته والتفاعل معه. يوضح هذا الدليل استخدام Ollama على النحو التالي: إما مع تطبيق Ollama عبر تكامل Hugging Face Hub أو نموذج محلي، أو مع حزمة llama-cpp-python.

استخدام تطبيق Ollama

يوفر تطبيق Ollama حلًا بسيطًا لتشغيل نماذج LLM محليًا. سهل الاستخدام، مع واجهة CLI تجعل عملية الإعداد بأكملها وإدارة النماذج والتفاعل معها أمرًا مباشرًا. مثالي للتجريب السريع وللمستخدمين الذين يريدون تفاصيل تقنية أقل.

تثبيت Ollama

1. نزّل تطبيق Ollama

2. ثبّت الملف الذي تم تنزيله

3. شغّل تطبيق Ollama المثبّت

   معلومات

   يعمل التطبيق بنجاح عندما تظهر أيقونة Ollama في شريط القوائم على سطح المكتب. يمكنك أيضًا التحقق من أن الخدمة تعمل بالانتقال إلى http://localhost:11434/.

4. جرّب Ollama في طرفيتك وابدأ تشغيل النماذج. مثلًا:

   ollama run hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit

إعداد Ollama باستخدام تكامل Hugging Face Hub

يوفر تكامل Ollama/Hugging Face Hub طريقة للتفاعل مع النماذج المستضافة على Hugging Face Hub دون الحاجة إلى إنشاء modelfile جديد أو تنزيل ملفات GGUF أو safetensors يدويًا. ملفات template وparams الافتراضية مُضمَّنة مسبقًا للنموذج على Hugging Face Hub.

1. تأكد من أن تطبيق Ollama يعمل.

2. اذهب إلى صفحة النموذج المطلوب وانسخ الرابط. مثلًا: https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

3. من طرفيتك، شغّل الأمر:

   ollama run hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit

يمكنك استخدام نموذج hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit أو أي من النماذج الرسمية GGUF الموصى بها حاليًا hf.co/Qiskit/mistral-small-3.2-24b-qiskit-GGUF أو hf.co/Qiskit/granite-3.3-8b-qiskit-GGUF.

إعداد Ollama مع نموذج GGUF لـ Qiskit Code Assistant تم تنزيله يدويًا

إذا قمت بتنزيل نموذج GGUF يدويًا مثل https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF وأردت تجربة templates وإعدادات مختلفة، يمكنك اتباع هذه الخطوات لتحميله في تطبيق Ollama المحلي.

1. أنشئ Modelfile بالمحتوى التالي وتأكد من تحديث <PATH-TO-GGUF-FILE> بالمسار الفعلي للنموذج الذي نزّلته.

   FROM <PATH-TO-GGUF-FILE>
   TEMPLATE """{{ if .System }}
   System:
   {{ .System }}
   
   {{ end }}{{ if .Prompt }}Question:
   {{ .Prompt }}
   
   {{ end }}Answer:
   ```python{{ .Response }}
   """
   
   PARAMETER stop "Question:"
   PARAMETER stop "Answer:"
   PARAMETER stop "System:"
   PARAMETER stop "```"
   
   PARAMETER temperature 0
   PARAMETER top_k 1

2. شغّل الأمر التالي لإنشاء مثيل نموذج مخصص بناءً على Modelfile.

   ollama create Qwen2.5-Coder-14B-Qiskit -f ./path-to-model-file

   ملاحظة

   قد تستغرق هذه العملية بعض الوقت حتى يقرأ Ollama ملف النموذج ويُهيّئ مثيل النموذج ويضبطه وفقاً للمواصفات المحددة.

تشغيل نموذج Qiskit Code Assistant المُحمَّل يدوياً في Ollama

بعد إعداد نموذج Qwen2.5-Coder-14B-Qiskit في Ollama، شغّل الأمر التالي لتشغيل النموذج والتفاعل معه في الطرفية (في وضع المحادثة).

ollama run Qwen2.5-Coder-14B-Qiskit

بعض الأوامر المفيدة:

• ollama list - عرض قائمة النماذج على جهازك
• ollama rm Qwen2.5-Coder-14B-Qiskit - حذف النموذج
• ollama show Qwen2.5-Coder-14B-Qiskit - عرض معلومات النموذج
• ollama stop Qwen2.5-Coder-14B-Qiskit - إيقاف نموذج قيد التشغيل حالياً
• ollama ps - عرض النماذج المحمّلة حالياً

نشر نماذج Qiskit Code Assistant محلياً عبر حزمة llama-cpp-python

بديل عن تطبيق Ollama هو حزمة llama-cpp-python، وهي واجهة ربط Python لمكتبة llama.cpp. توفّر لك مزيداً من التحكم والمرونة لتشغيل نموذج GGUF محلياً، وهي مثالية للمستخدمين الراغبين في دمج النموذج المحلي في سير عملهم وتطبيقات Python الخاصة بهم.

1. ثبّت llama-cpp-python
2. تفاعل مع النموذج من داخل تطبيقك باستخدام llama_cpp. على سبيل المثال:

from llama_cpp import Llama

model_path = <PATH-TO-GGUF-FILE>

model = Llama(
        model_path,
        seed=17,
        n_ctx=10000,
        n_gpu_layers=37, # to offload in gpu, but put 0 if all in cpu
    )

input = 'Generate a quantum circuit with 2 qubits'
raw_pred = model(input)["choices"][0]["text"]

يمكنك أيضاً إضافة معاملات توليد النص إلى النموذج لتخصيص الاستدلال:

generation_kwargs = {
        "max_tokens": 512,
        "echo": False, # Echo the prompt in the output
        "top_k": 1
    }

raw_pred = model(input, **generation_kwargs)["choices"][0]["text"]

نشر نماذج Qiskit Code Assistant محلياً عبر llama.cpp

استخدام مكتبة llama.cpp

بديل آخر هو استخدام llama.cpp، وهي مكتبة مفتوحة المصدر لتنفيذ استدلال نماذج اللغة الكبيرة على المعالج المركزي بأقل قدر من الإعداد. توفّر تحكماً منخفض المستوى في تنفيذ النموذج وتُشغَّل عادةً من سطر الأوامر مع الإشارة إلى ملف نموذج GGUF محلي.

هناك عدة طرق لتثبيت llama.cpp على جهازك:

• تثبيت llama.cpp باستخدام brew أو nix أو winget
• التشغيل عبر Docker: راجع توثيق Docker من فريق llama.cpp
• تنزيل الملفات التنفيذية الجاهزة من صفحة الإصدارات
• البناء من المصدر عبر استنساخ هذا المستودع

بعد التثبيت، يمكنك استخدام llama.cpp للتفاعل مع نماذج GGUF في وضع المحادثة كالتالي:

# Use a local model file
llama-cli -m my_model.gguf -cnv

# Or download and run a model directly from Hugging Face
llama-cli -hf Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF -cnv

يمكنك أيضاً تشغيل خادم API متوافق مع OpenAI للنموذج بالطريقة التالية:

llama-server -hf Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF

معاملات متقدمة

باستخدام برنامج llama-cli، يمكنك التحكم في توليد النموذج عبر خيارات سطر الأوامر. على سبيل المثال، يمكنك تقديم prompt نظام أولي باستخدام العلم -p/--prompt. في وضع المحادثة (-cnv)، يعمل هذا الـ prompt الأولي كرسالة النظام. وإلا يمكنك ببساطة إضافة أي تعليمات مطلوبة في بداية نص الـ prompt. يمكنك أيضاً ضبط معاملات أخذ العينات - مثلاً: درجة الحرارة (--temp)، وtop-k (--top-k)، وtop-p (--top-p)، وعقوبة التكرار (--repeat-penalty)، والبذرة (--seed). فيما يلي مثال على الاستدعاء باستخدام هذه الخيارات:

llama-cli -hf Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF \
  -p "You are a friendly assistant." -cnv \
  --temp 0.7 \
  --top-k 50 \
  --top-p 0.95 \
  --repeat-penalty 1.1 \
  --seed 42

لضمان الأداء الصحيح لنماذج Qiskit لدينا، نوصي باستخدام prompt النظام المقدَّم في مستودعات HF GGUF الخاصة بنا: prompt النظام لـ mistral-small-3.2-24b-qiskit-GGUF، وQwen2.5-Coder-14B-Qiskit-GGUF، وgranite-3.3-8b-qiskit-GGUF، وgranite-3.2-8b-qiskit-GGUF.

توصيل الإضافات بالنشر المحلي يدويًا

استخدم إضافة VS Code وإضافة JupyterLab لـ Qiskit Code Assistant للتفاعل مع نموذج Qiskit Code Assistant المنشور محليًا. بمجرد إعداد تطبيق Ollama مع النموذج، يمكنك تهيئة الإضافات للاتصال بالخدمة المحلية.

الاتصال بإضافة Qiskit Code Assistant لـ VS Code

مع إضافة Qiskit Code Assistant لـ VS Code، يمكنك التفاعل مع النموذج وإجراء إكمال الكود أثناء كتابته. يمكن أن يكون هذا مفيدًا جدًا للمستخدمين الذين يبحثون عن مساعدة في كتابة كود Qiskit لتطبيقات Python الخاصة بهم.

1. ثبّت إضافة Qiskit Code Assistant لـ VS Code.
2. في VS Code، اذهب إلى User Settings واضبط Qiskit Code Assistant: Url على رابط نشر Ollama المحلي لديك (مثلًا: http://localhost:11434).
3. أعد تحميل VS Code بالذهاب إلى View > Command Palette... واختيار Developer: Reload Window.

يجب أن يظهر نموذج Qiskit Code Assistant المُعدَّ في Ollama في شريط الحالة وهو جاهز للاستخدام.

الاتصال بإضافة Qiskit Code Assistant لـ JupyterLab

مع إضافة Qiskit Code Assistant لـ JupyterLab، يمكنك التفاعل مع النموذج وإجراء إكمال الكود مباشرةً في Jupyter Notebook. المستخدمون الذين يعملون أساسًا مع Jupyter Notebooks يمكنهم الاستفادة من هذه الإضافة لتعزيز تجربتهم في كتابة كود Qiskit.

1. ثبّت إضافة Qiskit Code Assistant لـ JupyterLab.
2. في JupyterLab، اذهب إلى Settings Editor واضبط Qiskit Code Assistant Service API على رابط نشر Ollama المحلي لديك (مثلًا: http://localhost:11434).

يجب أن يظهر نموذج Qiskit Code Assistant المُعدَّ في Ollama في شريط الحالة وهو جاهز للاستخدام.