الانتقال إلى المحتوى الرئيسي
يغطي هذا الدليل كيفية تهيئة مشروع CrewAI لتثبيت حزم Python من سجلات PyPI الخاصة (Azure DevOps Artifacts، GitHub Packages، GitLab، AWS CodeArtifact، إلخ.) عند النشر على CrewAI AMP.

​
متى تحتاج هذا

إذا كان مشروعك يعتمد على حزم Python داخلية أو خاصة مستضافة على سجل خاص بدلاً من PyPI العام، ستحتاج إلى:
  1. إخبار UV أين يجد الحزمة (رابط فهرس)
  2. إخبار UV أي حزم تأتي من ذلك الفهرس (تعيين مصدر)
  3. تقديم بيانات اعتماد حتى يتمكن UV من المصادقة أثناء التثبيت
يستخدم CrewAI AMP UV لحل وتثبيت الاعتماديات. يدعم UV السجلات الخاصة المصادق عليها عبر تهيئة pyproject.toml مع متغيرات بيئة لبيانات الاعتماد.

​
الخطوة 1: تهيئة pyproject.toml

ثلاثة أجزاء تعمل معاً في pyproject.toml:

​
1أ. التصريح بالاعتمادية

أضف الحزمة الخاصة إلى [project.dependencies] كأي اعتمادية أخرى: 
[project]
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

​
1ب. تعريف الفهرس

سجّل سجلك الخاص كفهرس مسمّى تحت [[tool.uv.index]]: 
[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true
حقل name مهم — يستخدمه UV لبناء أسماء متغيرات البيئة للمصادقة (راجع الخطوة 2 أدناه).تعيين explicit = true يعني أن UV لن يبحث في هذا الفهرس عن كل حزمة — فقط الحزم التي تعيّنها صراحة له في [tool.uv.sources]. يتجنب ذلك الاستعلامات غير الضرورية ضد سجلك الخاص ويحمي من هجمات ارتباك الاعتماديات.

​
1ج. تعيين الحزمة للفهرس

أخبر UV أي حزم يجب حلها من فهرسك الخاص باستخدام [tool.uv.sources]: 
[tool.uv.sources]
my-private-package = { index = "my-private-registry" }

​
مثال كامل

[project]
name = "my-crew-project"
version = "0.1.0"
requires-python = ">=3.10,<=3.13"
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

[tool.crewai]
type = "crew"

[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true

[tool.uv.sources]
my-private-package = { index = "my-private-registry" }
بعد تحديث pyproject.toml، أعد إنشاء ملف القفل: 
uv lock
ارفع دائماً uv.lock المُحدّث مع تغييرات pyproject.toml. ملف القفل مطلوب للنشر — راجع التحضير للنشر.

​
الخطوة 2: تعيين بيانات اعتماد المصادقة

يصادق UV ضد الفهارس الخاصة باستخدام متغيرات بيئة تتبع اصطلاح تسمية بناءً على اسم الفهرس الذي حددته في pyproject.toml: 
UV_INDEX_{UPPER_NAME}_USERNAME
UV_INDEX_{UPPER_NAME}_PASSWORD
حيث {UPPER_NAME} هو اسم فهرسك محوّلاً إلى أحرف كبيرة مع استبدال الشرطات بشرطات سفلية. على سبيل المثال، فهرس باسم my-private-registry يستخدم:
المتغيرالقيمة
UV_INDEX_MY_PRIVATE_REGISTRY_USERNAMEاسم مستخدم السجل أو اسم الرمز
UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORDكلمة مرور السجل أو الرمز/PAT
هذه المتغيرات يجب إضافتها عبر إعدادات Environment Variables في CrewAI AMP — إما عالمياً أو على مستوى النشر. لا يمكن تعيينها في ملفات .env أو ترميزها في مشروعك.راجع تعيين متغيرات البيئة في AMP أدناه.

​
مرجع مزودي السجلات

يوضح الجدول أدناه تنسيق رابط الفهرس وقيم بيانات الاعتماد لمزودي السجلات الشائعين. استبدل القيم المؤقتة بتفاصيل مؤسستك وخلاصتك الفعلية.
المزودرابط الفهرساسم المستخدمكلمة المرور
Azure DevOps Artifactshttps://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/أي نص غير فارغ (مثل token)Personal Access Token (PAT) بنطاق Packaging Read
GitHub Packageshttps://pypi.pkg.github.com/{owner}/simple/اسم مستخدم GitHubPersonal Access Token (classic) بنطاق read:packages
GitLab Package Registryhttps://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/__token__Project أو Personal Access Token بنطاق read_api
AWS CodeArtifactاستخدم الرابط من aws codeartifact get-repository-endpointawsرمز من aws codeartifact get-authorization-token
Google Artifact Registryhttps://{region}-python.pkg.dev/{project}/{repo}/simple/_json_key_base64مفتاح حساب الخدمة بتشفير Base64
JFrog Artifactoryhttps://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/اسم المستخدم أو البريد الإلكترونيمفتاح API أو رمز الهوية
مستضاف ذاتياً (devpi، Nexus، إلخ.)رابط Simple API لسجلكاسم مستخدم السجلكلمة مرور السجل
لـ AWS CodeArtifact، تنتهي صلاحية رمز التفويض دورياً. ستحتاج لتحديث قيمة UV_INDEX_*_PASSWORD عند انتهاء صلاحيتها. فكّر في أتمتة هذا في خط أنابيب CI/CD.

​
تعيين متغيرات البيئة في AMP

يجب تهيئة بيانات اعتماد السجل الخاص كمتغيرات بيئة في CrewAI AMP. لديك خياران:
  1. سجّل الدخول إلى CrewAI AMP
  2. انتقل إلى أتمتتك
  3. افتح علامة تبويب Environment Variables
  4. أضف كل متغير (UV_INDEX_*_USERNAME وUV_INDEX_*_PASSWORD) مع قيمته
راجع خطوة النشر على AMP — تعيين متغيرات البيئة للتفاصيل.
لا ترفع أبداً بيانات الاعتماد إلى مستودعك. استخدم متغيرات بيئة AMP لجميع الأسرار. يجب إدراج ملف .env في .gitignore.
لتحديث بيانات الاعتماد في نشر حالي، راجع تحديث طاقمك — متغيرات البيئة.

​
كيف يعمل الكل معاً

عندما يبني CrewAI AMP أتمتتك، يعمل تدفق الحل هكذا:
1

بدء البناء

يسحب AMP مستودعك ويقرأ pyproject.toml وuv.lock.
2

UV يحل الاعتماديات

يقرأ UV [tool.uv.sources] لتحديد أي فهرس يجب أن تأتي منه كل حزمة.
3

UV يصادق

لكل فهرس خاص، يبحث UV عن UV_INDEX_{NAME}_USERNAME وUV_INDEX_{NAME}_PASSWORD من متغيرات البيئة التي هيأتها في AMP.
4

تثبيت الحزم

يحمّل UV ويثبّت جميع الحزم — العامة (من PyPI) والخاصة (من سجلك).
5

تشغيل الأتمتة

يبدأ طاقمك أو تدفقك مع توفر جميع الاعتماديات.

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

​
أخطاء المصادقة أثناء البناء

العرض: فشل البناء بـ 401 Unauthorized أو 403 Forbidden عند حل حزمة خاصة. تحقق من:
  • أسماء متغيرات البيئة UV_INDEX_* تتطابق مع اسم فهرسك بالضبط (أحرف كبيرة، شرطات → شرطات سفلية)
  • بيانات الاعتماد معيّنة في متغيرات بيئة AMP، وليس فقط في .env محلي
  • الرمز/PAT لديه صلاحيات القراءة المطلوبة لخلاصة الحزم
  • الرمز لم تنتهِ صلاحيته (ذو صلة خاصة لـ AWS CodeArtifact)

​
الحزمة غير موجودة

العرض: No matching distribution found for my-private-package. تحقق من:
  • رابط الفهرس في pyproject.toml ينتهي بـ /simple/
  • إدخال [tool.uv.sources] يعيّن اسم الحزمة الصحيح لاسم الفهرس الصحيح
  • الحزمة منشورة فعلاً في سجلك الخاص
  • شغّل uv lock محلياً بنفس بيانات الاعتماد للتحقق من عمل الحل

​
تعارضات ملف القفل

العرض: فشل uv lock أو نتائج غير متوقعة بعد إضافة فهرس خاص. الحل: عيّن بيانات الاعتماد محلياً وأعد الإنشاء: 
export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
uv lock
ثم ارفع uv.lock المُحدّث.

​
أدلة ذات صلة

التحضير للنشر

تحقق من بنية المشروع والاعتماديات قبل النشر.

النشر على AMP

انشر طاقمك أو تدفقك وهيّئ متغيرات البيئة.

تحديث طاقمك

حدّث متغيرات البيئة وادفع التغييرات إلى نشر قائم.