مرجع API پایتون

پکیج aidin واسط‌های برنامه‌نویسی پایتون را برای تعریف مؤلفه‌ها، چیدمان پایپ‌لاین‌ها، کامپایل فایل‌های خروجی و اجرای آن‌ها روی پایپ‌لاین‌های آیدین فراهم می‌کند.

import aidin

# یا وارد کردن مستقیم نمادهای اصلی:
from aidin import (
    ProjectClient,
    compile,
    compile_pipeline,
    component,
    pipeline,
)

کامپایل و ساخت پایپ‌لاین‌ها

`aidin.compile`

یک تابع پایپ‌لاین را به پکیج مشخصات Pipeline در قالب KFP v2 YAML تبدیل می‌کند و در صورت نیاز، ایمیج کانتینر Docker را نیز می‌سازد. نام aidin.compile_pipeline نام مستعار هم‌ارز همین تابع است.

def compile(
    pipeline_func: Any,
    package_path: str,
    pipeline_name: Optional[str] = None,
    pipeline_parameters: Optional[Dict[str, Any]] = None,
    type_check: bool = True,
    build: bool = False,
    build_root_directory: Optional[str] = None,
    build_registry_address: Optional[str] = None,
) -> Optional[str]:

پارامترها

پارامتر	نوع	مقدار پیش‌فرض	توضیح
`pipeline_func`	`Callable`	(اجباری)	تابع پایتون نشانه‌گذاری‌شده با `@pipeline`.
`package_path`	`str`	(اجباری)	مسیر ذخیرهٔ فایل خروجی مشخصات YAML.
`pipeline_name`	`Optional[str]`	`None`	نام سفارشی پایپ‌لاین. پیش‌فرض بر مبنای نام تمیزشدهٔ تابع است.
`pipeline_parameters`	`Optional[Dict[str, Any]]`	`None`	مقادیر پارامترهای پیش‌فرض جهت تعبیه در مشخصات پایپ‌لاین.
`type_check`	`bool`	`True`	فعال بودن بررسی ایستا انواع ورودی و خروجی میان وظایف.
`build`	`bool`	`False`	در صورت `True` بودن، ایمیج کانتینر پروژه ساخته شده و آدرس ایمیج در YAML بازنویسی می‌شود.
`build_root_directory`	`Optional[str]`	`None`	مسیر ریشهٔ پروژه. در صورت فعال بودن `build=True` اجباری است.
`build_registry_address`	`Optional[str]`	`None`	آدرس رجیستری OCI برای بارگذاری ایمیج‌های ساخته‌شده. پیش‌فرض از `$AIDIN_REGISTRY_ADDRESS` یا `"harbor.aidin-ai.com/aidin-platform"`.

خروجی

Optional[str]: تگ ایمیج ساخته‌شده (مانند harbor.aidin-ai.com/aidin-platform/my-pipeline:20261109123456) در صورت build=True، در غیر این صورت None.

استثناها

ImportError: در صورتی که پکیج kfp در محیط نصب نشده باشد.
ValueError: در حالتی که build=True باشد اما مقدار build_root_directory مشخص نشده باشد.
FileNotFoundError: چنانچه فایل پکیج YAML ایجاد نشود یا خواندن آن برای به‌روزرسانی ایمیج با خطا مواجه گردد.

مثال

from aidin import compile
from my_project.pipelines import training_pipeline

# کامپایل ساده خط لوله:
compile(
    pipeline_func=training_pipeline,
    package_path="dist/training_pipeline.yaml",
)

# کامپایل همراه با ساخت یکپارچهٔ تصویر کانتینری:
image = compile(
    pipeline_func=training_pipeline,
    package_path="dist/training_pipeline.yaml",
    build=True,
    build_root_directory=".",
    build_registry_address="harbor.aidin-ai.com/aidin-platform",
)
print(f"خط لوله با تصویر کانتینری کامپایل شد: {image}")

لایهٔ DSL و دکوراتورهای مؤلفه

`aidin.component`

یک تابع پایتون را به یک مؤلفهٔ کانتینری سبک تبدیل کرده و مخزن پکیج‌ها و ایمیج‌های پیش‌فرض آیدین را به آن تزریق می‌کند.

def component(
    base_image: Optional[str] = None,
    packages_to_install: List[str] = [],
) -> Callable:

پارامترها

پارامتر	نوع	مقدار پیش‌فرض	توضیح
`base_image`	`Optional[str]`	`None`	ایمیج کانتینر جهت اجرای مؤلفه. در صورت عدم تعیین، از متغیر `$COMPS_BASE_IMAGE` یا `python:3.11` استفاده می‌شود.
`packages_to_install`	`List[str]`	`[]`	فهرست پکیج‌های پایتون که باید در زمان اجرای کانتینر مؤلفه نصب شوند.

بهبودهای اختصاصی آیدین

مؤلفه‌های تعریف‌شده با aidin.component از تنظیم آدرس مخزن پکیج‌ها از طریق متغیر محیطی پشتیبانی می‌کنند:

export AIDIN_PIP_INDEX_URL="https://hamgit.ir/api/v4/projects/23708/packages/pypi/simple"

در صورت عدم تنظیم، وابستگی‌ها بر اساس تنظیمات استاندارد محیط پایتون نصب می‌شوند.

انواع بازصادرشده در `aidin.dsl`

علاوه بر component و pipeline، تمامی انواع استاندارد Kubeflow Pipelines v2 از طریق aidin.dsl در دسترس هستند:

آرتیفکت‌های داده: Input، Output، Dataset، Model، Artifact، HTML، Markdown
متریک‌های ارزیابی: Metrics، ClassificationMetrics، SlicedClassificationMetrics
کنترل جریان: Condition، If، Elif، Else، ParallelFor، Collected، ExitHandler

مثال

from aidin.dsl import component, Input, Output, Dataset, Model, Metrics

@component(packages_to_install=["pandas", "scikit-learn"])
def train_model(
    train_data: Input[Dataset],
    model_artifact: Output[Model],
    metrics: Output[Metrics],
    n_estimators: int = 100,
) -> float:
    import pandas as pd
    from sklearn.ensemble import RandomForestClassifier
    import joblib

    df = pd.read_csv(train_data.path)
    X, y = df.drop(columns=["target"]), df["target"]

    clf = RandomForestClassifier(n_estimators=n_estimators)
    clf.fit(X, y)

    score = float(clf.score(X, y))
    metrics.log_metric("accuracy", score)

    joblib.dump(clf, model_artifact.path)
    return score

`aidin.pipeline`

دکوراتوری برای توابع پایتون که مؤلفه‌ها را در قالب یک گراف غیرمدور جهت‌دار (DAG) کنار هم می‌چیند.

def pipeline(
    func: Optional[Callable] = None,
    *,
    name: Optional[str] = None,
    description: Optional[str] = None,
) -> Callable:

پارامترها

پارامتر	نوع	مقدار پیش‌فرض	توضیح
`func`	`Optional[Callable]`	`None`	تابع تعریف پایپ‌لاین (هنگام استفاده به‌صورت دکوراتور بدون آرگومان `@pipeline`).
`name`	`Optional[str]`	`None`	نام نمایشی پایپ‌لاین. پیش‌فرض بر پایهٔ نام تابع است.
`description`	`Optional[str]`	`None`	شرح متنی کاربرد پایپ‌لاین.

مثال

from aidin.dsl import pipeline
from my_components import load_dataset, train_model, evaluate_model

@pipeline(
    name="customer-churn-prediction",
    description="بارگذاری داده‌ها، آموزش مدل و ارزیابی معیارهای آزمون."
)
def churn_pipeline(dataset_url: str, n_estimators: int = 100):
    dataset_task = load_dataset(url=dataset_url)
    train_task = train_model(
        train_data=dataset_task.outputs["dataset"],
        n_estimators=n_estimators,
    )
    evaluate_model(
        model=train_task.outputs["model_artifact"],
        test_data=dataset_task.outputs["dataset"],
    )

اتصال کلاینت و اجرای عملیات

`aidin.ProjectClient`

زیرکلاسی از kfp.Client که با استفاده از توکن‌های موقت حساب سرویس Kubernetes دریافتی از مبدل توکن آیدین پیکربندی می‌شود.

class ProjectClient(kfp.Client):
    def __init__(
        self,
        authentik_token: Optional[str] = None,
        project_name: Optional[str] = None,
        exchanger_url: Optional[str] = None,
        pipeline_server_url: Optional[str] = None,
        verify_ssl: bool = True,
        force_refresh: bool = False,
        aidin_user_dir: Optional[str] = None,
        *,
        timeout: float = 30.0,
        **kwargs: Any,
    )

پارامترها

پارامتر	نوع	مقدار پیش‌فرض	توضیح
`authentik_token`	`Optional[str]`	`None`	توکن بالادستی کاربر در Authentik. در صورت وجود توکن معتبر در کش می‌تواند `None` باشد. چنانچه به عنوان تنها آرگومان موقعیتی ارسال شود، به عنوان `project_name` تفسیر می‌شود.
`project_name`	`Optional[str]`	`None`	نام پروژهٔ آیدین (ارسال به شکل آرگومان موقعیتی یا کلیدواژه‌ای اجباری است).
`exchanger_url`	`Optional[str]`	`None`	آدرس مبدل توکن. پیش‌فرض `https://token-exchanger.<AIDIN_BASE_URL>`.
`pipeline_server_url`	`Optional[str]`	`None`	آدرس سرور API پایپ‌لاین‌های آیدین. پیش‌فرض `https://pipeline-server.<AIDIN_BASE_URL>`.
`verify_ssl`	`bool`	`True`	اعتبارسنجی گواهی‌های امنیتی TLS. در صورت `False` بودن، متغیر `KFP_SKIP_TLS_VERIFY="true"` به‌طور خودکار تنظیم می‌شود.
`force_refresh`	`bool`	`False`	در صورت `True` بودن، توکن جدید دریافت می‌شود حتی اگر کش معتبر باشد.
`aidin_user_dir`	`Optional[str]`	`None`	مسیر پایهٔ پوشهٔ کش توکن‌ها. پیش‌فرض `~/.aidin/`.
`timeout`	`float`	`30.0`	مهلت زمانی درخواست HTTP مبادلهٔ توکن به ثانیه.
`**kwargs`	`Any`		سایر آرگومان‌های اختیاری که مستقیماً به متد `kfp.Client.__init__` فرستاده می‌شوند.

ویژگی‌های سفارشی نمونهٔ کلاینت

client.aidin_project_name: str — نام پروژه/پروفایل متصل‌شده.
client.aidin_namespace: str — فضای نام Kubernetes مربوط به پروژه.
client.aidin_expires_at: Optional[str] — تایم‌استمپ انقضای توکن به فرمت ISO-8601 UTC.

متدهای به ارث رسیده از `kfp.Client`

کلاس ProjectClient همهٔ عملکردهای kfp.Client را پشتیبانی می‌کند:

upload_pipeline(pipeline_package_path, pipeline_name=None, description=None)
create_run_from_pipeline_func(pipeline_func, arguments=None, experiment_name=None, ...)
create_run_from_pipeline_package(pipeline_file, arguments=None, experiment_name=None, ...)
list_pipelines(page_token=None, page_size=10, sort_by=None)
get_experiment(experiment_id=None, experiment_name=None, namespace=None)
create_experiment(name, description=None, namespace=None)
wait_for_run_completion(run_id, timeout=None)

مثال: بارگذاری و ثبت اجرای پایپ‌لاین

import os
from aidin import ProjectClient
from my_pipeline import churn_pipeline

# مقداردهی اولیه کلاینت با توکن و پروژه:
client = ProjectClient(
    authentik_token=os.getenv("AUTHENTIK_TOKEN"),
    project_name="fraud-detection",
)

print(f"متصل به فضای نام: {client.aidin_namespace}")
print(f"زمان انقضای توکن: {client.aidin_expires_at}")

# ارسال مستقیم خط لوله برای اجرا از روی تابع پایتون:
run = client.create_run_from_pipeline_func(
    pipeline_func=churn_pipeline,
    arguments={"dataset_url": "https://data.example.com/churn.csv", "n_estimators": 200},
    experiment_name="churn-experiments",
)
print(f"اجرای خط لوله با شناسه ثبت شد: {run.run_id}")

گام‌های بعدی

بررسی گزینه‌های خط فرمان در مرجع ابزار خط فرمان.
جزئیات سازوکار امنیت در چرخهٔ حیات احراز هویت.

مرجع API پایتون

کامپایل و ساخت پایپ‌لاین‌ها

aidin.compile

پارامترها

خروجی

استثناها

مثال

لایهٔ DSL و دکوراتورهای مؤلفه

aidin.component

پارامترها

بهبودهای اختصاصی آیدین

انواع بازصادرشده در aidin.dsl

مثال

aidin.pipeline

پارامترها

مثال

اتصال کلاینت و اجرای عملیات

aidin.ProjectClient

پارامترها

ویژگی‌های سفارشی نمونهٔ کلاینت

متدهای به ارث رسیده از kfp.Client

مثال: بارگذاری و ثبت اجرای پایپ‌لاین

گام‌های بعدی

`aidin.compile`

`aidin.component`

انواع بازصادرشده در `aidin.dsl`

`aidin.pipeline`

`aidin.ProjectClient`

متدهای به ارث رسیده از `kfp.Client`