Skip to content

02-setup-local.md

Latest commit

 

History

History
232 lines (158 loc) · 11.8 KB

02-setup-local.md

File metadata and controls

232 lines (158 loc) · 11.8 KB

الإعداد المحلي 🖥️

استخدم هذا الدليل إذا كنت تفضل تشغيل كل شيء على جهاز اللابتوب الخاص بك.
لديك مساران: (أ) بايثون الأصلي + البيئة الافتراضية أو (ب) حاوية تطوير VS Code مع Docker.
اختر ما تشعر أنه أسهل—كلاهما يؤدي إلى نفس الدروس.

1. المتطلبات الأساسية

الأداة الإصدار / ملاحظات
بايثون 3.10 + (احصل عليه من https://python.org)
Git الأحدث (يأتي مع Xcode / Git لنظام ويندوز / مدير الحزم في لينكس)
VS Code اختياري لكن موصى به https://code.visualstudio.com
Docker Desktop فقط للخيار ب. تثبيت مجاني: https://docs.docker.com/desktop/

💡 نصيحة – تحقق من الأدوات في الطرفية:
python --version, git --version, docker --version, code --version

2. الخيار أ – بايثون الأصلي (الأسرع)

الخطوة 1 استنساخ هذا المستودع

git clone https://github.com/<your-github>/generative-ai-for-beginners
cd generative-ai-for-beginners

الخطوة 2 إنشاء وتفعيل بيئة افتراضية

python -m venv .venv          # اصنع واحدًا
source .venv/bin/activate     # ماك أو إس / لينكس
.\.venv\Scripts\activate      # ويندوز باورشيل

✅ يجب أن يبدأ الموجه الآن بـ (.venv)—هذا يعني أنك داخل البيئة.

الخطوة 3 تثبيت التبعيات

pip install -r requirements.txt

تخطى إلى القسم 3 حول مفاتيح API

2. الخيار ب – حاوية تطوير VS Code (Docker)

قمنا بإعداد هذا المستودع والدورة باستخدام حاوية تطوير تحتوي على بيئة تشغيل شاملة تدعم تطوير Python3 و .NET و Node.js و Java. التكوين المرتبط معرف في ملف devcontainer.json الموجود في مجلد .devcontainer/ في جذر هذا المستودع.

لماذا تختار هذا؟
بيئة مطابقة لـ Codespaces؛ لا انحراف في التبعيات.

الخطوة 0 تثبيت الإضافات

Docker Desktop – تأكد من عمل docker --version.
امتداد VS Code Remote – Containers (المعرف: ms-vscode-remote.remote-containers).

الخطوة 1 افتح المستودع في VS Code

ملف ▸ فتح مجلد… → generative-ai-for-beginners

يكتشف VS Code مجلد .devcontainer/ ويظهر موجه.

الخطوة 2 إعادة الفتح داخل الحاوية

انقر على "إعادة الفتح في الحاوية". يقوم Docker ببناء الصورة (≈ 3 دقائق في المرة الأولى).
عندما يظهر موجه الطرفية، تكون داخل الحاوية.

2. الخيار ج – Miniconda

Miniconda هو مثبت خفيف لتثبيت Conda، بايثون، وبعض الحزم.
Conda نفسها هي مدير حزم، تسهل إعداد والتبديل بين بيئات بايثون الافتراضية والحزم. كما أنها مفيدة لتثبيت الحزم غير المتوفرة عبر pip.

الخطوة 0 تثبيت Miniconda

اتبع دليل تثبيت MiniConda لإعداده.

conda --version

الخطوة 1 إنشاء بيئة افتراضية

أنشئ ملف بيئة جديد (environment.yml). إذا كنت تستخدم Codespaces، أنشئه داخل مجلد .devcontainer، أي .devcontainer/environment.yml.

الخطوة 2 ملء ملف البيئة الخاص بك

أضف المقتطف التالي إلى environment.yml

name: <environment-name>
channels:
 - defaults
 - microsoft
dependencies:
- python=<python-version>
- openai
- python-dotenv
- pip
- pip:
    - azure-ai-ml

الخطوة 3 إنشاء بيئة Conda الخاصة بك

شغّل الأوامر أدناه في سطر الأوامر/الطرفية

conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer الفرعي المسار ينطبق فقط على إعدادات Codespace
conda activate ai4beg

راجع دليل بيئات Conda إذا واجهت أي مشاكل.

2. الخيار د – Jupyter الكلاسيكي / Jupyter Lab (في متصفحك)

لمن هذا؟
لأي شخص يحب واجهة Jupyter الكلاسيكية أو يريد تشغيل دفاتر الملاحظات بدون VS Code.

الخطوة 1 تأكد من تثبيت Jupyter

لتشغيل Jupyter محليًا، توجه إلى الطرفية/سطر الأوامر، انتقل إلى مجلد الدورة، ونفذ:

jupyter notebook

أو

jupyterhub

سيبدأ هذا مثيل Jupyter وسيتم عرض عنوان URL للوصول إليه في نافذة سطر الأوامر.

بمجرد الوصول إلى العنوان، يجب أن ترى مخطط الدورة وتتمكن من التنقل إلى أي ملف *.ipynb. على سبيل المثال، 08-building-search-applications/python/oai-solution.ipynb.

3. أضف مفاتيح API الخاصة بك

الحفاظ على مفاتيح API الخاصة بك آمنة ومحمية أمر مهم عند بناء أي نوع من التطبيقات. نوصي بعدم تخزين أي مفاتيح API مباشرة في الكود الخاص بك. قد يؤدي الالتزام بهذه التفاصيل في مستودع عام إلى مشاكل أمنية وحتى تكاليف غير مرغوب فيها إذا استُخدمت من قبل جهة خبيثة.
إليك دليل خطوة بخطوة حول كيفية إنشاء ملف .env لبايثون وإضافة GITHUB_TOKEN:

  1. انتقل إلى مجلد مشروعك: افتح الطرفية أو موجه الأوامر وانتقل إلى جذر مشروعك حيث تريد إنشاء ملف .env.

    cd path/to/your/project

  2. إنشاء ملف .env: استخدم محرر النصوص المفضل لديك لإنشاء ملف جديد باسم .env. إذا كنت تستخدم سطر الأوامر، يمكنك استخدام touch (في أنظمة يونكس) أو echo (في ويندوز):

    أنظمة يونكس:

    touch .env

    ويندوز:

    echo . > .env

  3. تحرير ملف .env: افتح ملف .env في محرر نصوص (مثل VS Code، Notepad++، أو أي محرر آخر). أضف السطر التالي إلى الملف، مع استبدال your_github_token_here برمز GitHub الفعلي الخاص بك:

    GITHUB_TOKEN=your_github_token_here

  4. حفظ الملف: احفظ التغييرات وأغلق محرر النصوص.

  5. تثبيت python-dotenv: إذا لم تكن قد قمت بذلك، ستحتاج إلى تثبيت حزمة python-dotenv لتحميل متغيرات البيئة من ملف .env إلى تطبيق بايثون الخاص بك. يمكنك تثبيتها باستخدام pip:

    pip install python-dotenv

  6. تحميل متغيرات البيئة في سكريبت بايثون الخاص بك: في سكريبت بايثون، استخدم حزمة python-dotenv لتحميل متغيرات البيئة من ملف .env:

    from dotenv import load_dotenv
import os

# تحميل متغيرات البيئة من ملف .env
load_dotenv()

# الوصول إلى متغير GITHUB_TOKEN
github_token = os.getenv("GITHUB_TOKEN")

print(github_token)

هذا كل شيء! لقد أنشأت ملف .env بنجاح، وأضفت رمز GitHub الخاص بك، وحملته في تطبيق بايثون الخاص بك.

🔐 لا تلتزم بملف .env—فهو مدرج بالفعل في .gitignore.
تعليمات مزود الخدمة كاملة موجودة في providers.md.

4. ما التالي؟

أريد أن… اذهب إلى…
بدء الدرس 1 01-introduction-to-genai
إعداد مزود LLM providers.md
لقاء المتعلمين الآخرين انضم إلى Discord الخاص بنا

5. استكشاف الأخطاء وإصلاحها

العرض الحل
python not found أضف بايثون إلى PATH أو أعد فتح الطرفية بعد التثبيت
pip لا يمكنه بناء العجلات (ويندوز) pip install --upgrade pip setuptools wheel ثم أعد المحاولة.
ModuleNotFoundError: dotenv شغّل pip install -r requirements.txt (لم تُثبت البيئة).
فشل بناء Docker No space left Docker Desktop ▸ الإعدادات ▸ الموارد → زيادة حجم القرص.
VS Code يستمر في طلب إعادة الفتح قد يكون كلا الخيارين نشطين؛ اختر واحدًا (venv أو الحاوية)
أخطاء OpenAI 401 / 429 تحقق من قيمة OPENAI_API_KEY / حدود معدل الطلب.
أخطاء باستخدام Conda ثبّت مكتبات Microsoft AI باستخدام conda install -c microsoft azure-ai-ml

إخلاء المسؤولية:
تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية Co-op Translator. بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق به. للمعلومات الهامة، يُنصح بالاعتماد على الترجمة البشرية المهنية. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.