發布日期: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% 的用戶端處理作業,還是可以採用混合式做法?回答完這個問題後,下一步就是實作最適合您的模型下載策略。
請務必按照本指南的說明,向使用者顯示模型下載進度,確保他們隨時瞭解何時可以使用應用程式的用戶端。
請注意,這不是一次性挑戰:如果瀏覽器因儲存空間不足而清除模型,或是推出新版模型,瀏覽器就必須重新下載模型。無論您採用用戶端或混合式方法,都能確保為使用者打造最佳體驗,並讓瀏覽器處理其餘作業。