Prompt API

Thomas Steiner

Alexandra Klepper

Xuất bản: 20/5/2025, Cập nhật gần đây nhất: 21/9/2025

Người giải thích	Web	Phần mở rộng	Trạng thái của Chrome	Ý định
GitHub	Bản dùng thử theo nguyên gốc	Chrome 138	Xem	Ý định thử nghiệm

Với Prompt API, bạn có thể gửi các yêu cầu bằng ngôn ngữ tự nhiên đến Gemini Nano trong trình duyệt.

Có nhiều cách để sử dụng Prompt API. Ví dụ: bạn có thể xây dựng:

• Tính năng tìm kiếm dựa trên AI: Trả lời các câu hỏi dựa trên nội dung của một trang web.
• Nguồn cấp tin tức được cá nhân hoá: Xây dựng một nguồn cấp dữ liệu tự động phân loại các bài viết theo danh mục và cho phép người dùng lọc nội dung đó.
• Bộ lọc nội dung tuỳ chỉnh. Phân tích các bài viết tin tức và tự động làm mờ hoặc ẩn nội dung dựa trên các chủ đề do người dùng xác định.
• Tạo sự kiện trên lịch. Phát triển một Tiện ích Chrome tự động trích xuất thông tin chi tiết về sự kiện từ các trang web, để người dùng có thể tạo mục trên lịch chỉ trong vài bước.
• Trích xuất thông tin liên hệ liền mạch. Xây dựng một tiện ích trích xuất thông tin liên hệ từ các trang web, giúp người dùng dễ dàng liên hệ với một doanh nghiệp hoặc thêm thông tin chi tiết vào danh sách liên hệ của họ.

Đây chỉ là một vài khả năng và chúng tôi rất háo hức xem bạn sẽ tạo ra những gì.

Sử dụng Prompt API

Prompt API sử dụng mô hình Gemini Nano trong Chrome. Mặc dù API được tích hợp vào Chrome, nhưng mô hình này được tải xuống riêng biệt vào lần đầu tiên một nguồn gốc sử dụng API. Trước khi sử dụng API này, hãy xác nhận Chính sách về các hành vi bị cấm khi sử dụng AI tạo sinh của Google.

Để xác định xem mô hình đã sẵn sàng sử dụng hay chưa, hãy gọi LanguageModel.availability().

const availability = await LanguageModel.availability({
  // The same options in `prompt()` or `promptStreaming()`
});

Để kích hoạt quá trình tải xuống và tạo thực thể mô hình ngôn ngữ, hãy kiểm tra xem người dùng có kích hoạt hay không. Sau đó, hãy gọi hàm create() function.

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

Nếu phản hồi cho availability() là downloading, hãy theo dõi tiến trình tải xuống và thông báo cho người dùng, vì quá trình tải xuống có thể mất thời gian.

Sử dụng trên localhost

Tất cả các API AI tích hợp đều có trên localhost trong Chrome. Đặt các cờ sau thành Đã bật:

• chrome://flags/#optimization-guide-on-device-model
• chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

Sau đó, nhấp vào Khởi chạy lại hoặc khởi động lại Chrome. Nếu bạn gặp lỗi, hãy khắc phục sự cố localhost.

Tham số mô hình

Hàm params() thông báo cho bạn về các tham số của mô hình ngôn ngữ. Đối tượng có các trường sau:

• defaultTopK: Giá trị top-K mặc định.
• maxTopK: Giá trị top-K tối đa.
• defaultTemperature: Nhiệt độ mặc định .
• maxTemperature: Nhiệt độ tối đa.

// Only available when using the Prompt API for Chrome Extensions.
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

Tạo phiên

Sau khi Prompt API có thể chạy, bạn sẽ tạo một phiên bằng hàm create().

const session = await LanguageModel.create();

Tạo phiên bằng Prompt API dành cho Tiện ích Chrome

Khi bạn sử dụng Prompt API dành cho Tiện ích Chrome, mỗi phiên có thể được tuỳ chỉnh bằng topK và temperature bằng cách sử dụng một đối tượng tuỳ chọn không bắt buộc. Các giá trị mặc định cho các tham số này được trả về từ LanguageModel.params().

// Only available when using the Prompt API for Chrome Extensions.
const params = await LanguageModel.params();
// Initializing a new session must either specify both `topK` and
// `temperature` or neither of them.
// Only available when using the Prompt API for Chrome Extensions.
const slightlyHighTemperatureSession = await LanguageModel.create({
  temperature: Math.max(params.defaultTemperature * 1.2, 2.0),
  topK: params.defaultTopK,
});

Đối tượng tuỳ chọn không bắt buộc của hàm create() cũng lấy một trường signal, cho phép bạn truyền một AbortSignal để hủy bỏ phiên.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const session = await LanguageModel.create({
  signal: controller.signal,
});

Thêm ngữ cảnh bằng các câu lệnh ban đầu

Với các câu lệnh ban đầu, bạn có thể cung cấp cho mô hình ngôn ngữ ngữ cảnh về các lượt tương tác trước đó, chẳng hạn như cho phép người dùng tiếp tục một phiên đã lưu trữ sau khi khởi động lại trình duyệt.

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful and friendly assistant.' },
    { role: 'user', content: 'What is the capital of Italy?' },
    { role: 'assistant', content: 'The capital of Italy is Rome.' },
    { role: 'user', content: 'What language is spoken there?' },
    {
      role: 'assistant',
      content: 'The official language of Italy is Italian. [...]',
    },
  ],
});

Giới hạn phản hồi bằng tiền tố

Bạn có thể thêm vai trò "assistant" ngoài các vai trò trước đó để trình bày chi tiết về các phản hồi trước đó của mô hình. Ví dụ:

const followup = await session.prompt([
  {
    role: "user",
    content: "I'm nervous about my presentation tomorrow"
  },
  {
    role: "assistant",
    content: "Presentations are tough!"
  }
]);

Trong một số trường hợp, thay vì yêu cầu phản hồi mới, bạn có thể muốn điền sẵn một phần của thông báo phản hồi vai trò "assistant". Điều này có thể hữu ích để hướng dẫn mô hình ngôn ngữ sử dụng một định dạng phản hồi cụ thể. Để thực hiện việc này, hãy thêm prefix: true vào thông báo vai trò "assistant"- ở cuối. Ví dụ:

const characterSheet = await session.prompt([
  {
    role: 'user',
    content: 'Create a TOML character sheet for a gnome barbarian',
  },
  {
    role: 'assistant',
    content: '```toml\n',
    prefix: true,
  },
]);

Thêm thông tin đầu vào và đầu ra dự kiến

Prompt API có các khả năng đa phương thức và hỗ trợ nhiều ngôn ngữ. Đặt phương thức và ngôn ngữ expectedInputs và expectedOutputs khi tạo phiên.

• type: Phương thức dự kiến.
  • Đối với expectedInputs, đây có thể là text, image hoặc audio.
  • Đối với expectedOutputs, Prompt API chỉ cho phép text.
• languages: Mảng để đặt ngôn ngữ hoặc các ngôn ngữ dự kiến. Prompt API chấp nhận "en", "ja" và "es". Chúng tôi đang phát triển tính năng hỗ trợ thêm các ngôn ngữ khác.
  • Đối với expectedInputs, hãy đặt ngôn ngữ câu lệnh hệ thống và một hoặc nhiều ngôn ngữ câu lệnh dự kiến của người dùng.
  • Đặt một hoặc nhiều ngôn ngữ expectedOutputs.

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en" /* system prompt */, "ja" /* user prompt */] }
  ],
  expectedOutputs: [
    { type: "text", languages: ["ja"] }
  ]
});

Bạn có thể nhận được "NotSupportedError" DOMException nếu mô hình gặp phải thông tin đầu vào hoặc đầu ra không được hỗ trợ.

Khả năng đa phương thức

Với những khả năng này, bạn có thể:

• Cho phép người dùng phiên âm các tin nhắn âm thanh được gửi trong một ứng dụng trò chuyện.
• Mô tả một hình ảnh được tải lên trang web của bạn để sử dụng trong chú thích hoặc văn bản thay thế.

Hãy xem bản minh hoạ Câu lệnh âm thanh Mediarecorder để sử dụng Prompt API với đầu vào âm thanh và bản minh hoạ Câu lệnh hình ảnh Canvas demo để sử dụng Prompt API với đầu vào hình ảnh.

Prompt API hỗ trợ các loại thông tin đầu vào sau:

• Âm thanh:
  • AudioBuffer
  • ArrayBufferView
  • ArrayBuffer
  • Blob
• Hình ảnh:
  • HTMLImageElement
  • SVGImageElement
  • HTMLVideoElement (sử dụng khung video ở vị trí video hiện tại)
  • HTMLCanvasElement
  • ImageBitmap
  • OffscreenCanvas
  • VideoFrame
  • Blob
  • ImageData

Đoạn mã này cho thấy một phiên đa phương thức xử lý trước 2 hình ảnh (một hình ảnh Blob và một HTMLCanvasElement) và có AI so sánh chúng, sau đó cho phép người dùng phản hồi bằng bản ghi âm thanh (dưới dạng AudioBuffer).

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en"] },
    { type: "audio" },
    { type: "image" },
  ],
  expectedOutputs: [{ type: "text", languages: ["en"] }],
});

const referenceImage = await (await fetch("reference-image.jpeg")).blob();
const userDrawnImage = document.querySelector("canvas");

const response1 = await session.prompt([
  {
    role: "user",
    content: [
      {
        type: "text",
        value:
          "Give a helpful artistic critique of how well the second image matches the first:",
      },
      { type: "image", value: referenceImage },
      { type: "image", value: userDrawnImage },
    ],
  },
]);
console.log(response1);

const audioBuffer = await captureMicrophoneInput({ seconds: 10 });

const response2 = await session.prompt([
  {
    role: "user",
    content: [
      { type: "text", value: "My response to your critique:" },
      { type: "audio", value: audioBuffer },
    ],
  },
]);
console.log(response2);

Nối thêm thông báo

Quá trình suy luận có thể mất một chút thời gian, đặc biệt là khi đưa ra câu lệnh với thông tin đầu vào đa phương thức. Bạn nên gửi trước các câu lệnh đã xác định để điền vào phiên, để mô hình có thể bắt đầu xử lý.

Mặc dù initialPrompts hữu ích khi tạo phiên, nhưng bạn có thể sử dụng phương thức append() ngoài phương thức prompt() hoặc promptStreaming() để đưa ra các câu lệnh theo ngữ cảnh bổ sung sau khi tạo phiên.

Ví dụ:

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content:
        'You are a skilled analyst who correlates patterns across multiple images.',
    },
  ],
  expectedInputs: [{ type: 'image' }],
});

fileUpload.onchange = async () => {
  await session.append([
    {
      role: 'user',
      content: [
        {
          type: 'text',
          value: `Here's one image. Notes: ${fileNotesInput.value}`,
        },
        { type: 'image', value: fileUpload.files[0] },
      ],
    },
  ]);
};

analyzeButton.onclick = async (e) => {
  analysisResult.textContent = await session.prompt(userQuestionInput.value);
};

Lời hứa do append() trả về sẽ được thực hiện sau khi câu lệnh đã được xác thực, xử lý và nối thêm vào phiên. Lời hứa bị từ chối nếu không thể nối thêm câu lệnh.

Truyền JSON Schema

Thêm trường responseConstraint vào phương thức prompt() hoặc promptStreaming() để truyền JSON Schema làm giá trị. Sau đó, bạn có thể sử dụng đầu ra có cấu trúc với Prompt API.

Trong ví dụ sau, JSON Schema đảm bảo mô hình phản hồi bằng true hoặc false để phân loại xem một thông báo nhất định có liên quan đến đồ gốm hay không.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended, but that
happens with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(
  `Is this post about pottery?\n\n${post}`,
  {
    responseConstraint: schema,
  }
);
console.log(JSON.parse(result));
// true

Phương thức triển khai của bạn có thể bao gồm JSON Schema hoặc biểu thức chính quy như một phần của thông báo được gửi đến mô hình. Phương thức này sử dụng một số cửa sổ ngữ cảnh. Bạn có thể đo lường mức sử dụng cửa sổ ngữ cảnh bằng cách truyền tuỳ chọn responseConstraint đến session.measureContextUsage().

Bạn có thể tránh hành vi này bằng tuỳ chọn omitResponseConstraintInput. Nếu làm như vậy, bạn nên đưa ra một số hướng dẫn trong câu lệnh:

const result = await session.prompt(`
  Summarize this feedback into a rating between 0-5. Only output a JSON
  object { rating }, with a single property whose value is a number:
  The food was delicious, service was excellent, will recommend.
`, { responseConstraint: schema, omitResponseConstraintInput: true });

Đưa ra câu lệnh cho mô hình

Bạn có thể đưa ra câu lệnh cho mô hình bằng hàm prompt() hoặc promptStreaming().

Đầu ra dựa trên yêu cầu

Nếu dự kiến kết quả ngắn, bạn có thể sử dụng hàm prompt() trả về phản hồi sau khi có phản hồi.

// Start by checking if it's possible to create a session based on the
// availability of the model, and the characteristics of the device.
const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});

if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and wait for the whole result to come back.
  const result = await session.prompt('Write me a poem!');
  console.log(result);
}

Đầu ra được truyền trực tuyến

Nếu dự kiến phản hồi dài hơn, bạn nên sử dụng hàm promptStreaming(), cho phép bạn hiển thị kết quả một phần khi chúng được gửi đến từ mô hình. Hàm promptStreaming() trả về một ReadableStream.

const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and stream the result:
  const stream = session.promptStreaming('Write me an extra-long poem!');
  for await (const chunk of stream) {
    console.log(chunk);
  }
}

Dừng đưa ra câu lệnh

Cả prompt() và promptStreaming() đều chấp nhận tham số thứ hai không bắt buộc có trường signal, cho phép bạn dừng chạy câu lệnh.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const result = await session.prompt('Write me a poem!', {
  signal: controller.signal,
});

Quản lý phiên

Mỗi phiên đều theo dõi ngữ cảnh của cuộc trò chuyện. Các lượt tương tác trước đó được tính đến cho các lượt tương tác trong tương lai cho đến khi cửa sổ ngữ cảnh của phiên đầy.

Mỗi phiên có số lượng mã thông báo tối đa mà phiên đó có thể xử lý. Kiểm tra tiến trình của bạn đối với giới hạn này bằng cách sau:

console.log(`${session.contextUsage}/${session.contextWindow}`);

Bạn có thể gửi một câu lệnh khiến cửa sổ ngữ cảnh bị tràn. Trong những trường hợp như vậy, các phần ban đầu của cuộc trò chuyện với mô hình ngôn ngữ sẽ bị xoá, mỗi lần một cặp câu lệnh và phản hồi, cho đến khi có đủ mã thông báo để xử lý câu lệnh mới. Ngoại lệ là câu lệnh hệ thống, câu lệnh này không bao giờ bị xoá.

Bạn có thể phát hiện các trường hợp tràn như vậy bằng cách theo dõi sự kiện contextoverflow trên phiên:

session.addEventListener("contextoverflow", () => {
  console.log("We've gone past the context window, and some inputs will be dropped!");
});

Nếu không thể xoá đủ token khỏi nhật ký cuộc trò chuyện để xử lý câu lệnh mới, thì lệnh gọi prompt() hoặc promptStreaming() sẽ không thành công với ngoại lệ QuotaExceededError và không có gì bị xoá. QuotaExceededError có các thuộc tính sau:

• requested: số lượng mã thông báo mà thông tin đầu vào bao gồm
• contextWindow: số lượng mã thông báo có sẵn

Tìm hiểu thêm về cách quản lý phiên.

Sao chép phiên

Để giữ nguyên tài nguyên, bạn có thể sao chép một phiên hiện có bằng hàm clone(). Thao tác này sẽ tạo một nhánh của cuộc trò chuyện, trong đó ngữ cảnh và câu lệnh ban đầu được giữ nguyên.

Hàm clone() lấy một đối tượng tuỳ chọn không bắt buộc có trường signal, cho phép bạn truyền một AbortSignal để huỷ phiên đã sao chép.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const clonedSession = await session.clone({
  signal: controller.signal,
});

Chấm dứt phiên

Gọi destroy() để giải phóng tài nguyên nếu bạn không cần phiên nữa. Khi một phiên bị huỷ, bạn không thể sử dụng phiên đó nữa và mọi quá trình thực thi đang diễn ra đều bị huỷ. Bạn có thể muốn giữ phiên nếu dự định thường xuyên đưa ra câu lệnh cho mô hình, vì việc tạo phiên có thể mất một chút thời gian.

await session.prompt(
  "You are a friendly, helpful assistant specialized in clothing choices."
);

session.destroy();

// The promise is rejected with an error explaining that
// the session is destroyed.
await session.prompt(
  "What should I wear today? It is sunny, and I am choosing between a t-shirt
  and a polo."
);

Bản minh hoạ

Chúng tôi đã xây dựng nhiều bản minh hoạ để khám phá nhiều trường hợp sử dụng cho Prompt API. Các bản minh hoạ sau đây là ứng dụng web:

• Sân chơi Prompt API
• Câu lệnh âm thanh Mediarecorder
• Câu lệnh hình ảnh Canvas

Để kiểm thử Prompt API trong Tiện ích Chrome, hãy cài đặt tiện ích minh hoạ. Bạn có thể tìm thấy mã nguồn của tiện ích trên GitHub.

Chiến lược hiệu suất

Prompt API dành cho web vẫn đang được phát triển. Trong khi chúng tôi xây dựng API này, hãy tham khảo các phương pháp hay nhất của chúng tôi về cách quản lý phiên để có hiệu suất tối ưu.

Chính sách về quyền, iframe và Web Worker

Theo mặc định, Prompt API chỉ có sẵn cho các cửa sổ cấp cao nhất và các iframe cùng nguồn gốc. Bạn có thể uỷ quyền truy cập vào API cho các iframe nhiều nguồn gốc bằng cách sử dụng thuộc tính allow="" của Chính sách về quyền:

<!--
  The hosting site at https://main.example.com can grant a cross-origin iframe
  at https://cross-origin.example.com/ access to the Prompt API by
  setting the `allow="language-model"` attribute.
-->
<iframe src="https://cross-origin.example.com/" allow="language-model"></iframe>

Prompt API hiện không có trong Web Worker do sự phức tạp của việc thiết lập một tài liệu có trách nhiệm cho mỗi worker để kiểm tra trạng thái chính sách về quyền.

Tham gia và chia sẻ ý kiến phản hồi

Ý kiến của bạn có thể ảnh hưởng trực tiếp đến cách chúng tôi xây dựng và triển khai các phiên bản trong tương lai của API này và tất cả các API AI tích hợp.

• Để đưa ra ý kiến phản hồi về cách triển khai của Chrome, hãy gửi báo cáo lỗi hoặc yêu cầu về tính năng.
• Chia sẻ ý kiến phản hồi về hình dạng API bằng cách bình luận về một Vấn đề hiện có hoặc bằng cách mở một vấn đề mới trong kho lưu trữ Prompt API GitHub.
• Tham gia chương trình dùng thử sớm.