‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

شروع به کار با Prompt API

این صفحه نحوه انجام کارهای زیر را شرح می‌دهد:

پیکربندی پروژه برای استفاده از Prompt API
ارائه ورودی فقط نوشتاری و دریافت پاسخ
ورودی‌های تصویری را با ورودی نوشتاری مرتبط ارائه دهید و پاسخ دریافت کنید

برای جزئیات بیشتر درباره Prompt API، به اسناد مرجع Kotlin (com.google.mlkit.genai.prompt) و Java (com.google.mlkit.genai.prompt.java، com.google.mlkit.genai.prompt) مراجعه کنید.

پیکربندی پروژه

‫ML Kit Prompt API را به‌عنوان وابستگی در پیکربندی build.gradle اضافه کنید:

implementation("com.google.mlkit:genai-prompt:1.0.0-beta4")

اگر به پاسخ‌هایتان در قالب خاصی بااستفاده از Structured Output API نیاز دارید، باید KSP را پیکربندی کنید و وابستگی‌های بیشتری اضافه کنید. برای جزئیات بیشتر، تولید برونداد ساختاریافته را ببینید.

پیاده‌سازی مدل زایا

برای پیاده‌سازی کد در پروژه‌تان، این مراحل را دنبال کنید:

ایجاد شیء generativeModel:

Kotlin

// Get a GenerativeModel instance
val generativeModel = Generation.getClient()

جاوا

// Get a GenerativeModel instance
GenerativeModelFutures generativeModelFutures = GenerativeModelFutures
    .from(Generation.INSTANCE.getClient());

بررسی کنید Gemini Nano AVAILABLE, DOWNLOADABLE یا UNAVAILABLE باشد. سپس، اگر ویژگی بارگیری‌شدنی است، آن را بارگیری کنید:

Kotlin

val status = generativeModel.checkStatus()
when (status) {
    FeatureStatus.UNAVAILABLE -> {
        // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
    }

    FeatureStatus.DOWNLOADABLE -> {
        // Gemini Nano can be downloaded on this device, but is not currently downloaded
        generativeModel.download().collect { status ->
            when (status) {
                is DownloadStatus.DownloadStarted ->
                    Log.d(TAG, "starting download for Gemini Nano")

                is DownloadStatus.DownloadProgress ->
                    Log.d(TAG, "Nano ${status.totalBytesDownloaded} bytes downloaded")

                DownloadStatus.DownloadCompleted -> {
                    Log.d(TAG, "Gemini Nano download complete")
                    modelDownloaded = true
                }

                is DownloadStatus.DownloadFailed -> {
                    Log.e(TAG, "Nano download failed ${status.e.message}")
                }
            }
        }
    }

    FeatureStatus.DOWNLOADING -> {
        // Gemini Nano currently being downloaded
    }

    FeatureStatus.AVAILABLE -> {
        // Gemini Nano currently downloaded and available to use on this device
    }
}

جاوا

ListenableFuture<Integer> status = generativeModelFutures.checkStatus();
Futures.addCallback(generativeModelFutures.checkStatus(), new FutureCallback<>() {
    @Override
    public void onSuccess(Integer featureStatus) {
        switch (featureStatus) {
            case FeatureStatus.AVAILABLE - > {
                // Gemini Nano currently downloaded and available to use on this device
            }
            case FeatureStatus.UNAVAILABLE - > {
                // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
            }
            case FeatureStatus.DOWNLOADING - > {
                // Gemini Nano currently being downloaded
            }
            case FeatureStatus.DOWNLOADABLE - > {
                generativeModelFutures.download(new DownloadCallback() {
                    @Override
                    public void onDownloadStarted(long l) {
                        Log.d(TAG, "starting download for Gemini Nano");
                    }
                    @Override
                    public void onDownloadProgress(long l) {
                        Log.d(TAG, "Nano " + l + " bytes downloaded");
                    }
                    @Override
                    public void onDownloadCompleted() {
                        Log.d(TAG, "Gemini Nano download complete");
                    }
                    @Override
                    public void onDownloadFailed(@NonNull GenAiException e) {
                        Log.e(TAG, "Nano download failed: " + e.getMessage());
                    }
                });
            }
        }
    }
    @Override
    public void onFailure(@NonNull Throwable t) {
        // Failed to check status
    }
}, ContextCompat.getMainExecutor(context));

ارائه ورودی فقط نوشتاری

Kotlin

val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog.")

جاوا

GenerateContentResponse response = generativeModelFutures.generateContent(
  new GenerateContentRequest.Builder(
    new TextPart("Write a 3 sentence story about a magical dog."))
  .build())
  .get();

یا پارامترهای اختیاری را اضافه کنید:

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(
        TextPart("Write a 3 sentence story about a magical dog."),
    ) {
        // Optional parameters
        temperature = 0.2f
        topK = 10
        candidateCount = 3
    },
)

جاوا

GenerateContentRequest.Builder requestBuilder =
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."));
requestBuilder.setTemperature(.2f);
requestBuilder.setTopK(10);
requestBuilder.setCandidateCount(3);

GenerateContentResponse response =
        generativeModelFutures.generateContent(requestBuilder.build()).get();

برای اطلاعات بیشتر درباره پارامترهای اختیاری، پیکربندی‌های اختیاری را ببینید.

ارائه ورودی چندحالتی (تصویر و نوشتار)

چند تصویر و یک ورودی نوشتاری را در تابع generateContentRequest() باهم بسته‌بندی کنید، به‌طوری‌که پیام‌واره نوشتاری یک سؤال یا فرمان مربوط به تصویر باشد. می‌توانید حداکثر ۱۰ تصویر را در یک درخواست بسته‌بندی کنید.

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(ImagePart(bitmap1), ImagePart(bitmap2), TextPart(textPrompt)) {
        // optional parameters
        ...
    },
)

جاوا

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new Content.Builder()
            .addPart(new ImagePart(bitmap1))
            .addPart(new ImagePart(bitmap2))
            .addPart(new TextPart("textPrompt"))
            .build())
    // optional parameters
    .build())
.get();

پردازش نتیجه استنتاج

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

این روش از استنتاج غیرجاری‌سازی استفاده می‌کند که کل نتیجه را از مدل هوش مصنوعی بازیابی می‌کند و سپس نتیجه را برمی‌گرداند:

Kotlin

// Call the AI model to generate content and store the complete
// in a new variable named 'response' once it's finished
val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog")

جاوا

GenerateContentResponse response = generativeModelFutures.generateContent(
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."))
                .build())
        .get();

قطعه‌های زیر نمونه‌هایی از استفاده از استنتاج جاری‌سازی هستند که نتیجه را به‌صورت تکه‌تکه درحین تولید بازیابی می‌کند:

Kotlin

// Streaming inference
var fullResponse = ""
generativeModel.generateContentStream("Write a 3 sentence story about a magical dog").collect { chunk ->
    val newChunkReceived = chunk.candidates[0].text
    print(newChunkReceived)
    fullResponse += newChunkReceived
}

جاوا

// Streaming inference
StringBuilder fullResponse = new StringBuilder();
generativeModelFutures.generateContent(new GenerateContentRequest.Builder(
    (new TextPart("Write a 3 sentence story about a magical dog"))).build(),
        chunk -> {
            Log.d(TAG, chunk);
            fullResponse.append(chunk);
        });

برای اطلاعات بیشتر درباره استنتاج جاری‌سازی و غیرجاری‌سازی، به جاری‌سازی درمقابل غیرجاری‌سازی مراجعه کنید.

بهینه‌سازی تأخیر

برای بهینه‌سازی اولین فراخوانی استنتاج، برنامه شما می‌تواند به‌صورت اختیاری warmup() را فراخوانی کند. این کار Gemini Nano را در حافظه بار می‌کند و مؤلفه‌های زمان اجرا را مقداردهی اولیه می‌کند.

پیکربندی‌های اختیاری

به‌عنوان بخشی از هر GenerateContentRequest، می‌توانید پارامترهای اختیاری زیر را تنظیم کنید:

temperature : میزان تصادفی بودن را در انتخاب داده‌واحد کنترل می‌کند.
seed : تولید نتایج پایدار و قطعی را فعال می‌کند.
topK : تصادفی بودن و تنوع نتایج را کنترل می‌کند.
‫candidateCount : تعداد پاسخ‌های یکتای برگردانده‌شده را درخواست می‌کند. توجه داشته باشید که تعداد دقیق پاسخ‌ها ممکن است با candidateCount یکسان نباشد زیرا پاسخ‌های تکراری به‌طور خودکار برداشته می‌شوند.
maxOutputTokens : حداکثر تعداد داده‌واحدهایی را که می‌توان در پاسخ تولید کرد تعریف می‌کند.

برای راهنمایی بیشتر درباره تنظیم پیکربندی‌های اختیاری، به GenerateContentRequest مراجعه کنید.

ویژگی‌ها و محدودیت‌های پشتیبانی‌شده

ورودی باید کمتر از ۴۰۰۰ واحد (یا تقریباً ۳۰۰۰ کلمه انگلیسی) باشد. برای اطلاعات بیشتر، به مرجع countTokens مراجعه کنید.
از موارد استفاده‌ای که به برونداد طولانی (بیش‌از ۴ هزار توکن) نیاز دارند باید اجتناب شود.
AICore سهمیه استنتاجی را برای هر برنامه اعمال می‌کند. برای اطلاعات بیشتر، سهمیه برای هر برنامه را ببینید.

مشکلات رایج راه‌اندازی

میاناهای برنامه‌سازی کاربردی ML Kit GenAI برای دسترسی به Gemini Nano به برنامه Android AICore متکی هستند. وقتی دستگاه به‌تازگی راه‌اندازی شده است (ازجمله بازنشانی)، یا برنامه AICore به‌تازگی بازنشانی شده است (مثلاً پاک کردن داده‌ها، حذف نصب و سپس نصب مجدد)، ممکن است برنامه AICore زمان کافی برای تکمیل مقداردهی اولیه (ازجمله بارگیری جدیدترین پیکربندی‌ها از سرور) نداشته باشد. درنتیجه، میاناهای برنامه‌سازی کاربردی GenAI در ML Kit ممکن است عملکرد موردانتظار را نداشته باشند. در اینجا پیام‌های خطای رایج راه‌اندازی که ممکن است ببینید و نحوه رسیدگی به آن‌ها آورده شده است:

نمونه پیام خطا	نحوه رسیدگی
‫AICore با نوع خطای 4-CONNECTION_ERROR و کد خطای 601-BINDING_FAILURE ناموفق بود: سرویس AICore متصل نشد.	این اتفاق ممکن است زمانی رخ دهد که برنامه را بااستفاده از ML Kit GenAI APIs بلافاصله پس‌از راه‌اندازی دستگاه نصب کنید یا زمانی که AICore پس‌از نصب برنامه شما حذف نصب شود. به‌روزرسانی برنامه AICore و سپس بازنصب کردن برنامه شما باید مشکل را برطرف کند.
‫AICore با نوع خطای 3-PREPARATION_ERROR و کد خطای 606-FEATURE_NOT_FOUND ناموفق بود: ویژگی ... دردسترس نیست.	این اتفاق زمانی می‌افتد که AICore بارگیری جدیدترین پیکربندی‌ها را به‌پایان نرسانده باشد. وقتی دستگاه به اینترنت متصل باشد، معمولاً چند دقیقه تا چند ساعت طول می‌کشد تا به‌روز شود. بازراه‌اندازی دستگاه می‌تواند به‌روزرسانی را تسریع کند. توجه داشته باشید که اگر قفل bootloader دستگاه باز باشد، این خطا را نیز خواهید دید—این API از دستگاه‌هایی که قفل bootloader آن‌ها باز است پشتیبانی نمی‌کند.
‫AICore با نوع خطای 1-DOWNLOAD_ERROR و کد خطای 0-UNKNOWN ناموفق بود: ویژگی ... با وضعیت ناموفق 0 و خطای esz: UNAVAILABLE: Unable to resolve host ... ناموفق بود	اتصال شبکه را حفظ کنید، چند دقیقه صبر کنید و دوباره امتحان کنید.

شروع به کار با Prompt API با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیکربندی پروژه

پیاده‌سازی مدل زایا

Kotlin

جاوا

Kotlin

جاوا

ارائه ورودی فقط نوشتاری

Kotlin

جاوا

Kotlin

جاوا

ارائه ورودی چندحالتی (تصویر و نوشتار)

Kotlin

جاوا

پردازش نتیجه استنتاج

Kotlin

جاوا

Kotlin

جاوا

بهینه‌سازی تأخیر

پیکربندی‌های اختیاری

ویژگی‌ها و محدودیت‌های پشتیبانی‌شده

مشکلات رایج راه‌اندازی

شروع به کار با Prompt API