آموزش هوش مصنوعی

سرویس هوش مصنوعی در جاوا؛ محیط توسعه، پیکربندی امن و قرارداد درخواست

متوسط مطالعه در ۸ دقیقه بخش ۵۹ از ۶۰ در مبانی هوش مصنوعی و علم داده
mahdyar
سرویس هوش مصنوعی در جاوا؛ محیط توسعه، پیکربندی امن و قرارداد درخواست

سرویس هوش مصنوعی در جاوا معمولاً با یک نمونه‌کد شروع می‌شود که روی لپ‌تاپ یک نفر کار می‌کند. کلید API در کد است، نسخه‌ی JDK فقط روی همان سیستم نصب است و اگر سرویس مدل کند شود، کل برنامه قفل می‌شود. فاصله‌ی این نمونه تا سرویسی که تیم بتواند رویش حساب کند، در همین جزئیات به‌ظاهر کوچک است.

در قسمت ۵۲ چهار الگوی پایه‌ی هوش مصنوعی در جاوا را دیدیم. در این قسمت روی زیرساخت و مرز سرویس تمرکز می‌کنیم. محیط توسعه را قابل تکرار می‌کنیم، منابع ابری را با کد می‌سازیم، پیکربندی را امن می‌کنیم و قراردادی برای ورودی و خروجی سرویس طراحی می‌کنیم.

محیط توسعه قابل تکرار

«روی سیستم من کار می‌کند» یکی از قدیمی‌ترین مشکلات توسعه‌ی نرم‌افزار است. در پروژه‌های هوش مصنوعی، نسخه‌ی JDK، نسخه‌ی SDK و ابزارهای خط فرمان باید برای همه یکسان باشد. محیط قابل تکرار این مشکل را حل می‌کند.

Dev Container و Codespaces

درس اصلی از Dev Container استفاده می‌کند. یک فایل پیکربندی در مخزن تعیین می‌کند محیط توسعه چه ابزارهایی دارد؛ JDK نسخه‌ی ۲۱، Maven، Azure CLI و ابزار azd. هر عضو تیم با باز کردن مخزن در VS Code یا GitHub Codespaces دقیقاً همان محیط را می‌گیرد.

مزیت دیگرش شروع سریع است. عضو تازه‌ی تیم به جای یک روز نصب و پیکربندی، در چند دقیقه آماده‌ی کار است. و وقتی نسخه‌ی ابزاری عوض می‌شود، فقط یک فایل در مخزن تغییر می‌کند.

ساخت منابع ابری با کد

منابع ابری، مثل پروژه‌ی Azure AI Foundry و استقرار مدل، را با دست در پورتال نسازید. درس اصلی از ابزار azd و قالب‌های Bicep استفاده می‌کند. یک دستور azd up همه‌ی منابع را طبق تعریف مخزن می‌سازد.

این رویکرد زیرساخت به‌عنوان کد نام دارد. محیط آزمون و محیط اصلی از یک تعریف ساخته می‌شوند و تفاوت پنهانی ندارند. اگر محیطی خراب شد، از روی همان کد دوباره ساخته می‌شود. و تغییرات زیرساخت هم مثل کد بازبینی می‌شوند.

پیکربندی امن و آزمون اتصال

سرویس هوش مصنوعی به چند مقدار پیکربندی نیاز دارد؛ نشانی سرویس مدل، نام استقرار مدل و اطلاعات احراز هویت. نحوه‌ی نگه‌داری این مقادیر روی امنیت و قابلیت نگه‌داری اثر مستقیم دارد.

بدون راز در مخزن

هیچ کلید یا رازی نباید در کد یا فایل‌های مخزن باشد. نشانی و نام استقرار را از متغیرهای محیطی بخوانید. در توسعه‌ی محلی، azd env get-values این مقادیر را از منابع ساخته‌شده برمی‌گرداند. فایل محلی محیط هم باید در فهرست نادیده‌گرفته‌شده‌های Git باشد.

برای احراز هویت، همان روش بدون کلید قسمت ۵۲ را به کار ببرید. در توسعه‌ی محلی، هویت ورود توسعه‌دهنده و در سرور، هویت مدیریت‌شده. اگر سرویسی فقط کلید می‌پذیرد، کلید را در مخزن راز نگه دارید و در زمان اجرا بخوانید.

آزمون اتصال پیش از هر چیز

پیش از نوشتن منطق سرویس، یک آزمون اتصال ساده بنویسید. یک درخواست کوتاه به مدل بفرستد و مطمئن شود پاسخ می‌آید. اگر شکست خورد، پیام خطا باید روشن بگوید مشکل از کجاست؛ نشانی، نام استقرار، دسترسی یا شبکه.

این آزمون را در راه‌اندازی سرویس هم اجرا کنید؛ یک نقطه‌ی پایانی سلامت که وضعیت اتصال به مدل را گزارش دهد. وقتی سرویس در محیط اصلی شکست می‌خورد، اولین سؤال این است که مدل در دسترس است یا نه. پاسخ باید در چند ثانیه معلوم شود.

بیشتر بخوانید: چهار الگوی پایه‌ی چت، فراخوانی تابع، RAG و پاسخ فیلترشده در جاوا را در هوش مصنوعی مولد در جاوا ساختیم.

قرارداد درخواست؛ مرز سرویس

قرارداد درخواست تعیین می‌کند سرویس چه چیزی می‌گیرد و چه چیزی برمی‌گرداند. این قرارداد مصرف‌کنندگان را از جزئیات مدل جدا می‌کند. اگر فردا مدل را عوض کنید، برنامه‌هایی که از سرویس استفاده می‌کنند نباید تغییر کنند. نمودار زیر لایه‌های یک سرویس هوش مصنوعی قابل اعتماد را نشان می‌دهد.

لایه‌های سرویس هوش مصنوعی در جاوا از قرارداد درخواست تا نگاشت خطا

ورودی و خروجی صریح

ورودی و خروجی را با کلاس‌های صریح تعریف کنید، نه با رشته‌ی آزاد. در جاوا، record برای این کار عالی است. ورودی را اعتبارسنجی کنید؛ پرسش خالی یا خیلی طولانی پیش از رسیدن به مدل رد شود. خروجی هم علاوه بر متن پاسخ، منبع‌ها و یک شناسه‌ی درخواست برای ردیابی داشته باشد:

java
public record AskRequest(@NotBlank @Size(max = 2000) String question, String courseId) {}
public record AskResponse(String answer, List<String> sources, String requestId) {}

@RestController
@RequestMapping("/api/v1/assistant")
class AssistantController {
    private final AssistantService service;
    AssistantController(AssistantService service) { this.service = service; }

    @PostMapping("/ask")
    AskResponse ask(@Valid @RequestBody AskRequest req) {
        return service.ask(req);
    }
}

نسخه‌ی قرارداد

به /api/v1 در مسیر دقت کنید. اگر روزی شکل ورودی یا خروجی باید تغییر ناسازگار کند، نسخه‌ی دو را کنار نسخه‌ی یک منتشر کنید. مصرف‌کنندگان فرصت دارند به‌تدریج مهاجرت کنند.

قرارداد را مستند کنید. ابزارهایی مثل OpenAPI مستندات را از خود کد می‌سازند. مصرف‌کننده بدون خواندن کد سرویس می‌داند چه بفرستد و چه انتظار داشته باشد.

مهلت، تلاش دوباره و نگاشت خطا

سرویس مدل یک وابستگی بیرونی است و گاهی کند یا ناموجود است. سرویس شما باید برای این لحظه‌ها طراحی شده باشد، نه اینکه با آن‌ها قفل شود.

مهلت و تلاش دوباره

برای هر درخواست به مدل، مهلت تعیین کنید. بدون مهلت، یک درخواست گیرکرده یک رشته‌ی سرور را برای همیشه نگه می‌دارد. با چند درخواست گیرکرده، کل سرویس از کار می‌افتد.

برای خطاهای موقت، مثل ۴۲۹ به معنای عبور از سقف درخواست یا خطاهای ۵۰۳، تلاش دوباره با تأخیر نمایی کمک می‌کند. تعداد تلاش را محدود کنید و اگر سرویس زمان انتظار پیشنهادی فرستاده، رعایتش کنید. برای خطاهای دائمی، مثل ۴۰۱ یا ورودی نامعتبر، تلاش دوباره فقط هزینه اضافه می‌کند.

نگاشت خطا و لاگ امن

خطای داخلی سرویس مدل را مستقیم به مصرف‌کننده نفرستید. آن را به خطاهای قرارداد خودتان نگاشت کنید. ورودی نامعتبر ۴۰۰، شلوغی موقت ۵۰۳ با زمان پیشنهادی تلاش دوباره، و پاسخ فیلترشده یک پیام روشن با کد مشخص.

در لاگ، شناسه‌ی درخواست، مدت پاسخ، تعداد توکن و نوع خطا را ثبت کنید. متن کامل پرسش کاربر را ثبت نکنید، مگر با دلیل روشن و رعایت حریم خصوصی. همان اصل حداقل داده‌ی لازم که در قسمت اخلاق داده دیدیم، اینجا هم صادق است.

تمرین عملی؛ سرویس دستیار آموزشی

یک سرویس Spring Boot کوچک با این ویژگی‌ها بسازید:

  • محیط: یک Dev Container با JDK ۲۱ و Maven تعریف کنید.
  • پیکربندی: نشانی و نام استقرار را از متغیر محیطی بخوانید و مطمئن شوید هیچ رازی در مخزن نیست.
  • سلامت: یک نقطه‌ی پایانی سلامت با آزمون اتصال به مدل بسازید.
  • قرارداد: AskRequest و AskResponse را با اعتبارسنجی پیاده کنید.
  • خطاها: مهلت، تلاش دوباره برای ۴۲۹ و نگاشت خطا به کدهای قرارداد را اضافه کنید.

در پایان، سرویس مدل را عمداً در دسترس خارج کنید؛ مثلاً نام استقرار را اشتباه بگذارید. ببینید سرویس شما چه پاسخی می‌دهد. اگر پیام روشن و سریع بود، طراحی درست است.

سخن پایانی

سرویس هوش مصنوعی در جاوا با محیط توسعه‌ی قابل تکرار، منابع ابری ساخته‌شده با کد و پیکربندی بدون راز شروع می‌شود. آزمون اتصال و نقطه‌ی پایانی سلامت، عیب‌یابی را از ساعت‌ها به دقیقه‌ها می‌رساند.

قرارداد درخواست صریح با اعتبارسنجی و نسخه، مصرف‌کنندگان را از جزئیات مدل جدا می‌کند. مهلت، تلاش دوباره‌ی محدود، نگاشت خطا و لاگ امن هم سرویس را در برابر کندی و خطای وابستگی بیرونی مقاوم می‌کنند.

این آموزش بر پایه‌ی فصل Setting up the Development Environment از مجموعه‌ی آزاد Generative AI for Beginners Java مایکروسافت (مجوز MIT) به فارسی بازنویسی و تکمیل شده است.

پرسش‌های پرتکرار

برای ساخت سرویس هوش مصنوعی در جاوا چه ابزارهایی لازم است؟

یک JDK جدید مثل نسخه‌ی ۲۱، ابزار ساخت Maven یا Gradle، یک کلاینت مدل مثل OpenAI Java SDK یا Spring AI، و دسترسی به یک سرویس مدل. برای یکسان بودن محیط تیم، Dev Container یا GitHub Codespaces کمک زیادی می‌کند.

چرا نباید کلید API را در کد یا فایل پیکربندی مخزن گذاشت؟

چون هر کسی که به مخزن دسترسی دارد یا تاریخچه‌ی آن را ببیند، کلید را هم می‌بیند و کلید نشت‌کرده می‌تواند هزینه‌ی سنگین یا نشت داده بسازد. کلید را از متغیر محیطی یا مخزن راز بخوانید و در صورت امکان از احراز هویت بدون کلید استفاده کنید.

قرارداد درخواست در سرویس هوش مصنوعی یعنی چه؟

یعنی تعریف دقیق شکل ورودی و خروجی سرویس؛ چه فیلدهایی الزامی‌اند، چه محدودیت طولی دارند و پاسخ و خطا چه شکلی دارند. این قرارداد مصرف‌کننده را از جزئیات مدل جدا می‌کند و تغییر مدل را بدون شکستن برنامه‌های دیگر ممکن می‌کند.

با خطای ۴۲۹ سرویس مدل چه کنیم؟

خطای ۴۲۹ یعنی از سقف درخواست عبور کرده‌اید. با تأخیر نمایی و سقف تعداد تلاش دوباره درخواست را تکرار کنید، هدر زمان انتظار را اگر سرویس فرستاده رعایت کنید و به مصرف‌کننده پیام روشن بدهید، نه خطای داخلی نامفهوم.

دیدگاه‌ها

هنوز دیدگاهی ثبت نشده است. شروع‌کننده باشید — پرسش و اصلاح را با آغوش باز می‌پذیریم.

دیدگاه بگذارید

برای **پررنگ**، *مورب*، `کد` و لینک از Markdown استفاده کنید. لینک‌ها nofollow هستند.

پنج رقم داخل تصویر را وارد کنید. اعداد فارسی و انگلیسی پذیرفته می‌شوند.

تصویر کد امنیتی پنج‌رقمی

در حال دریافت کد امنیتی…

مهلت کد تمام شد. روی «کد جدید» بزنید.