通知使用者模型下載情形

發布日期:2025 年 10 月 1 日

如要使用任何內建 AI API,必須先從網路下載基礎模型和任何自訂項目 (例如微調),解壓縮壓縮資料,最後載入記憶體。本指南記錄了幾項最佳做法,可協助您在使用者等待下載時提升使用者體驗。

監控及分享下載進度

每個內建 AI API 都有 create() 函式,可啟動工作階段。create() 函式具有 monitor 選項,因此您可以存取下載進度,並與使用者分享。

內建 AI API 專為用戶端 AI 而設計,可在瀏覽器和使用者裝置上處理資料,但部分應用程式可允許在伺服器上處理資料。您在模型下載進度中如何稱呼使用者,取決於這個問題:資料處理是否必須只能在本機執行?如果為 true,您的應用程式就只會使用用戶端。 如果沒有,應用程式可以使用混合式實作

僅限用戶端

在某些情況下,您必須處理用戶端資料。舉例來說,如果醫療保健應用程式允許病患詢問個人資訊相關問題,這類資訊可能就只會儲存在使用者的裝置上。使用者必須等到模型和所有自訂項目下載完成並準備就緒,才能使用任何資料處理功能。

在這種情況下,如果模型尚未提供,您應向使用者顯示下載進度資訊。

<style>
  progress[hidden] ~ label {
    display: none;
  }
</style>

<button type="button">Create LanguageModel session</button>
<progress hidden id="progress" value="0"></progress>
<label for="progress">Model download progress</label>

下載內建模型時,您還無法使用應用程式。

現在需要一些 JavaScript 才能讓這個功能運作。程式碼會先將進度介面重設為初始狀態 (隱藏進度並設為零),檢查是否支援 API,然後檢查 API 的可用性

  • API 是 'unavailable':您的應用程式無法在這個裝置上以用戶端形式使用。提醒使用者這項功能無法使用。
  • API 為 'available':可立即使用,不需顯示進度 UI。
  • API 為 'downloadable''downloading':下載完成後即可使用 API。顯示進度指標,並在每次觸發 downloadprogress 事件時更新。下載完成後,請向使用者顯示不確定狀態,表示瀏覽器正在擷取模型並載入記憶體。
const createButton = document.querySelector('.create');
const promptButton = document.querySelector('.prompt');
const progress = document.querySelector('progress');
const output = document.querySelector('output');

let sessionCreationTriggered = false;
let session = null;

const createSession = async (options = {}) => {
  if (sessionCreationTriggered) {
    return;
  }

  progress.hidden = true;
  progress.value = 0;

  try {
    if (!('LanguageModel' in self)) {
      throw new Error('LanguageModel is not supported.');
    }

    const availability = await LanguageModel.availability();
    if (availability === 'unavailable') {
      throw new Error('LanguageModel is not available.');
    }

    let modelNewlyDownloaded = false;
    if (availability !== 'available') {
      modelNewlyDownloaded = true;
      progress.hidden = false;
    }
    console.log(`LanguageModel is ${availability}.`);
    sessionCreationTriggered = true;

    const llmSession = await LanguageModel.create({
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          progress.value = e.loaded;
          if (modelNewlyDownloaded && e.loaded === 1) {
            // The model was newly downloaded and needs to be extracted
            // and loaded into memory, so show the undetermined state.
            progress.removeAttribute('value');
          }
        });
      },
      ...options,
    });

    sessionCreationTriggered = false;
    return llmSession;
  } catch (error) {
    throw error;
  } finally {
    progress.hidden = true;
    progress.value = 0;
  }
};

createButton.addEventListener('click', async () => {
  try {
    localSession = await createSession({
      expectedInputs: [{ type: 'text', languages: ['en'] }],
      expectedOutputs: [{ type: 'text', languages: ['en'] }],
    });
    promptButton.disabled = false;
  } catch (error) {
    output.textContent = error.message;
  }
});

promptButton.addEventListener('click', async () => {
  output.innerHTML = '';
  try {
    const stream = localSession.promptStreaming('Write me a poem');
    for await (const chunk of stream) {
      output.append(chunk);
    }
  } catch (err) {
    output.textContent = err.message;
  }
});

如果使用者在模型主動下載至瀏覽器時進入應用程式,進度介面會根據仍缺少的資料,指出瀏覽器在下載程序中的位置。

請觀看示範影片,瞭解這個流程的實際運作方式。如果內建的 AI API (在本範例中為 Prompt API) 無法使用,就無法使用應用程式。如果內建 AI 模型仍需下載,系統會向使用者顯示進度指標。您可以在 GitHub 上查看原始碼

混合式導入

如果您偏好使用用戶端 AI,但可以暫時將資料傳送至雲端,可以設定混合式實作。也就是說,使用者可以立即體驗各項功能,同時下載本機模型。模型下載完成後,動態切換至本機工作階段。

您可以為混合式實作使用任何伺服器端實作,但最好在雲端和本機都使用相同的模型系列,確保獲得品質相當的結果。開始使用 Gemini API 和網頁應用程式: 重點介紹 Gemini API 的各種方法。

下載內建模型時,應用程式會改用雲端模型,因此仍可正常運作。

請參閱 這個範例,瞭解實際運作情形。如果內建 AI API 無法使用,這個試用版會改用雲端中的 Gemini API。如果仍需下載內建模型,系統會向使用者顯示進度指標,且應用程式會使用雲端中的 Gemini API,直到模型下載完成為止。查看 GitHub 上的完整原始碼

結論

您的應用程式屬於哪個類別?您是否需要 100% 的用戶端處理作業,還是可以採用混合式做法?回答完這個問題後,下一步就是實作最適合您的模型下載策略。

請務必按照本指南的說明,向使用者顯示模型下載進度,確保他們隨時瞭解何時可以使用應用程式的用戶端。

請注意,這不是一次性挑戰:如果瀏覽器因儲存空間不足而清除模型,或是推出新版模型,瀏覽器就必須重新下載模型。無論您採用用戶端或混合式方法,都能確保為使用者打造最佳體驗,並讓瀏覽器處理其餘作業。