نمای کلی SDK پایتون

SDK پایتون آیدین (aidin) ابزاری سطح‌بالا برای تعریف، کامپایل و دیپلوی پایپ‌لاین‌های ML روی پلتفرم آیدین است؛ پایپ‌لاین‌ها روی موتور مدیریت‌شدهٔ KFP v2 (Kubeflow Pipelines v2) اجرا می‌شوند.

نسخهٔ 0.4.0 کنترل‌های سخت‌گیرانه‌تری بر چرخهٔ حیات احراز هویت، ذخیره‌سازی امن و مبتنی بر هویت اطلاعات نشست، و سازگاری کامل با KFP v2 ارائه می‌دهد.

معماری

SDK آیدین بر چهار لایهٔ اساسی بنا شده است:

+-------------------------------------------------------------+
|                         کد برنامه‌نویس                       |
|   @aidin.component             @aidin.pipeline              |
+-------------------------------------------------------------+
|                      لایهٔ شفاف DSL                          |
|  - تزریق شاخص بستهٔ پایتون قابل تنظیم (AIDIN_PIP_INDEX_URL) |
|  - تزریق تصویر پایه پیش‌فرض (COMPS_BASE_IMAGE)               |
|  - بازصادرات انواع، آرتیفکت‌ها و کنترل جریان KFP v2         |
+-------------------------------------------------------------+
|                     موتور ساخت و کامپایل                    |
|  - کامپایل تعاریف پایتون به مشخصات YAML نسخه دوم KFP         |
|  - امکان ساخت و بارگذاری تصویر کانتینر (harbor.aidin-ai.com)|
|  - بازنویسی خودکار مرجع تصویر در بستهٔ نهایی YAML            |
+-------------------------------------------------------------+
|             زمان اجرای کلاینت و چرخهٔ احراز هویت            |
|  - جریان Authentik -> مبدل توکن -> TokenRequest کوبرنتیز     |
|  - کش محلی امن (~/.aidin/<project>/token.json با سطح 0600)  |
|  - اعتبارسنجی انقضا با احتساب انحراف زمانی (حاشیهٔ ۶۰ ثانیه)|
|  - کلاس ProjectClient با توسعهٔ kfp.Client                   |
+-------------------------------------------------------------+

۱. لایهٔ شفاف DSL (`aidin.dsl`)

این SDK یک لایهٔ انتزاع شفاف بر فراز kfp.dsl فراهم می‌کند. برنامه‌نویسان می‌توانند تمامی دکوراتورهای استاندارد KFP، انواع آرتیفکت‌ها (Input، Output، Dataset، Model)، متریک‌های ارزیابی، و عملگرهای کنترل جریان (Condition، ParallelFor، ExitHandler) را مستقیماً از aidin.dsl وارد کنند.

آیدین با پیکربندی خودکار موارد زیر، مؤلفه‌های استاندارد را ارتقا می‌دهد:

آدرس اندکس پکیج‌های پایتون از طریق AIDIN_PIP_INDEX_URL برای پکیج‌های مشخص‌شده در packages_to_install (پیش‌فرض بدون وابستگی به زیرساخت غیرفعال).
ایمیج‌های کانتینری پایه بر اساس متغیر محیطی COMPS_BASE_IMAGE یا پیش‌فرض python:3.11.

۲. موتور کامپایل و بسته‌بندی (`aidin.compile`)

موتور کامپایل توابع پایپ‌لاینِ پایتون را به پکیج‌های YAML در قالب KFP v2 تبدیل می‌کند. هنگامی که ماژول‌های پروژه یا وابستگی‌های سفارشی میان مؤلفه‌ها به اشتراک گذاشته می‌شوند، فلگ --build یک ایمیج کانتینری یکپارچه ایجاد کرده، آن را به رجیستری Harbor (harbor.aidin-ai.com/aidin-platform) ارسال می‌کند و مراجع ایمیج‌ها را در YAML تولیدشده بازنویسی می‌کند.

۳. احراز هویت و چرخهٔ اطلاعات نشست (`aidin.shared.auth`)

این SDK با سرویس هویت بالادستی Authentik و سرویس داخلی Aidin Token Exchanger در تعامل است. توکن کاربر با یک توکن موقت حساب سرویس Kubernetes در فضای نام مربوط به پروژه مبادله می‌شود. توکن‌های بالادستی کاربر هرگز روی دیسک ذخیره نمی‌شوند و توکن‌های موقت ذخیره‌شده دارای سطح دسترسی سخت‌گیرانهٔ POSIX (0600) هستند.

۴. کلاینت پروژه (`aidin.ProjectClient`)

کلاس ProjectClient مستقیماً از kfp.Client مشتق شده و پایپ‌لاین‌ها را با استفاده از اطلاعات احراز هویت بررسی‌شده و انتخاب خودکار فضای نام پروژه، به سرور پایپ‌لاین‌های آیدین متصل می‌کند.

نسخه‌های پشتیبانی‌شدهٔ پایتون

SDK آیدین نیازمند شرایط زیر است:

پایتون نسخهٔ ۳.۹ به بالا (>= 3.9) (آزمایش‌شده روی پایتون ۳.۹، ۳.۱۰ و ۳.۱۱).
پایتون ۳.۱۴ در حال حاضر به دلیل محدودیت پکیج‌های بالادستی kfp پشتیبانی نمی‌شود.

نحوهٔ نصب

از طریق مخزن پکیج‌های پایتون هم‌گیت (GitLab PyPI)

برای نصب پکیج رسمی از مخزن بومی هم‌گیت:

pip install aidin --index-url https://__token__:<your_token>@hamgit.ir/api/v4/projects/23708/packages/pypi/simple

در صورت پیکربندی در فایل pip.conf:

[global]
extra-index-url = https://__token__:<your_token>@hamgit.ir/api/v4/projects/23708/packages/pypi/simple

ایمیج کانتینر آماده برای اجرا در Kubernetes (Harbor)

ایمیج کانتینر مینیمال با امنیت بالا و کاربر غیر ریشه (non-root) در رجیستری Harbor منتشر شده است:

docker pull harbor.aidin-ai.com/aidin-platform/aidin-sdk:0.4.0

ارجاع قطعی از طریق دایجست غیرقابل تغییر:

harbor.aidin-ai.com/aidin-platform/aidin-sdk@sha256:28c605b3e05dc3c4b32d332bf9c8ab7873412206fa8b7aeb917b3e86c8928946

نصب از سورس‌کد

برای توسعهٔ داخلی یا مشارکت:

git clone git@hamgit.ir:adin/mlops/sdk/new-sdk.git
cd new-sdk
pip install -e .

بررسی صحت نصب

برای اطمینان از نصب صحیح و بررسی شمارهٔ نسخه:

aidin --version

خروجی مورد انتظار:

aidin, version 0.4.0

وابستگی‌های اصلی

پکیج	شرط نسخه	کاربرد
`kfp`	`>=2.4.0, <3.0.0`	کامپایلر اصلی پایپ‌لاین‌ها و زمان اجرای کلاینت Kubeflow Pipelines
`click`	`>=8.0.0`	چارچوب مدیریت رابط خط فرمان
`requests`	`>=2.28.0`	برقراری ارتباط با سرویس مبدل توکن آیدین

گام‌های بعدی

مطالعهٔ چرخهٔ حیات احراز هویت برای درک نحوهٔ مبادله و امنیت توکن‌ها.
مشاهدهٔ دستورات در مرجع ابزار خط فرمان.
بررسی مستندات توابع و کلاس‌ها در مرجع API پایتون.