發布日期:2025 年 10 月 1 日
如要使用任何內建 AI API,必須先下載基礎模型和所有自訂項目 (例如微調),解壓縮壓縮資料,然後將所有內容載入記憶體。最佳做法是提醒使用者下載這些檔案所需的時間。
下列範例使用 Prompt API,但這些概念適用於所有其他內建 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':可立即使用 API,不必顯示進度 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 localSession = 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({
// ⚠️ Always pass the same options to the `availability()` function that
// you use in `prompt()` or `promptStreaming()`. This is critical to
// align model language and modality capabilities.
expectedInputs: [{ type: 'text', languages: ['en'] }],
expectedOutputs: [{ type: 'text', languages: ['en'] }],
});
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 和 Web 應用程式: 這篇文章重點介紹 Gemini API 的各種方法。

混合式展示
請參閱 示範 ,瞭解實際運作情形。如果內建 AI API 無法使用,這個試用版會改用雲端中的 Gemini API。如果仍需下載內建模型,系統會向使用者顯示進度指標,且應用程式會使用雲端中的 Gemini API,直到模型下載完成為止。查看 GitHub 上的完整原始碼。
結論
您的應用程式屬於哪個類別?您是否需要 100% 的用戶端處理作業,還是可以採用混合式做法?回答完這個問題後,下一步就是實作最適合您的模型下載策略。
請務必向使用者顯示模型下載進度,確保他們隨時瞭解何時可以使用應用程式用戶端,如本指南所述。
請注意,這不是一次性挑戰:如果瀏覽器因儲存空間不足而清除模型,或有新模型版本可用時,瀏覽器需要再次下載模型。無論您採用用戶端或混合式方法,都能確保為使用者打造最佳體驗,並讓瀏覽器處理其餘作業。