Multimodal Live API

API Trực tiếp đa phương thức cho phép tương tác hai chiều bằng giọng nói và video với độ trễ thấp thông qua Gemini. Khi sử dụng API Trực tiếp đa phương thức, bạn có thể mang đến cho người dùng cuối trải nghiệm trò chuyện tự nhiên, giống như con người bằng giọng nói, đồng thời có thể ngắt lời phản hồi của mô hình bằng lệnh thoại. Mô hình này có thể xử lý dữ liệu đầu vào văn bản, âm thanh và video, đồng thời có thể cung cấp dữ liệu đầu ra văn bản và âm thanh.

Tính năng

API Trực tiếp đa phương thức bao gồm các chức năng chính sau:

• Tính đa phương thức: Mô hình có thể nhìn, nghe và nói.
• Tương tác theo thời gian thực có độ trễ thấp: Cung cấp phản hồi nhanh.
• Bộ nhớ phiên: Mô hình giữ lại bộ nhớ của tất cả các lượt tương tác trong một phiên, gợi nhắc thông tin đã nghe hoặc nhìn thấy trước đó.
• Hỗ trợ gọi hàm, thực thi mã và Tìm kiếm dưới dạng công cụ: Cho phép tích hợp với các dịch vụ và nguồn dữ liệu bên ngoài.
• Phát hiện hoạt động giọng nói tự động (VAD): Mô hình có thể nhận dạng chính xác thời điểm người dùng bắt đầu và dừng nói. Điều này cho phép các tương tác tự nhiên, trò chuyện và cho phép người dùng làm gián đoạn mô hình bất cứ lúc nào.

Bạn có thể dùng thử API Trực tiếp đa phương thức trong Google AI Studio.

Bắt đầu

Multimodal Live API là một API có trạng thái sử dụng WebSockets.

Phần này trình bày ví dụ về cách sử dụng API trực tiếp đa phương thức để tạo văn bản sang văn bản bằng Python 3.9 trở lên.

Cài đặt thư viện Gemini API

Để cài đặt gói google-genai, hãy sử dụng lệnh pip sau:

!pip3 install google-genai

Nhập phần phụ thuộc

Cách nhập phần phụ thuộc:

from google import genai

Gửi và nhận tin nhắn văn bản

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Hướng dẫn tích hợp

Phần này mô tả cách tích hợp với API Trực tiếp đa phương thức.

Phiên

Một phiên đại diện cho một kết nối WebSocket duy nhất giữa ứng dụng và máy chủ Gemini.

Sau khi ứng dụng khởi tạo một kết nối mới, phiên có thể trao đổi thông báo với máy chủ để:

• Gửi văn bản, âm thanh hoặc video đến máy chủ Gemini.
• Nhận phản hồi âm thanh, văn bản hoặc lệnh gọi hàm từ máy chủ Gemini.

Cấu hình phiên được gửi trong thông báo đầu tiên sau khi kết nối. Cấu hình phiên bao gồm mô hình, thông số tạo, hướng dẫn hệ thống và các công cụ.

Hãy xem cấu hình mẫu sau:

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

Để biết thêm thông tin, hãy xem BidiGenerateContentSetup.

Gửi tin nhắn

Thông báo là các chuỗi có định dạng JSON được trao đổi qua kết nối WebSocket.

Để gửi thông báo, ứng dụng phải gửi thông báo ứng dụng được hỗ trợ ở dạng chuỗi được định dạng JSON qua một trong các kết nối WebSocket đang mở.

Tin nhắn được hỗ trợ của ứng dụng

Xem các thông báo ứng dụng được hỗ trợ trong bảng sau:

Nhận tin nhắn

Để nhận thông báo từ Gemini, hãy theo dõi sự kiện "message" (thông báo) của WebSocket, sau đó phân tích cú pháp kết quả theo định nghĩa của thông báo máy chủ được hỗ trợ.

Xem các mục sau đây:

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

Thông báo máy chủ được hỗ trợ

Xem các thông báo máy chủ được hỗ trợ trong bảng sau:

Cập nhật nội dung tăng dần

Sử dụng các bản cập nhật gia tăng để gửi dữ liệu nhập văn bản, thiết lập hoặc khôi phục ngữ cảnh phiên. Đối với ngữ cảnh ngắn, bạn có thể gửi các lượt tương tác từng chặng để thể hiện trình tự chính xác của các sự kiện. Đối với các ngữ cảnh dài hơn, bạn nên cung cấp một bản tóm tắt tin nhắn duy nhất để giải phóng cửa sổ ngữ cảnh cho các lượt tương tác tiếp theo.

Xem thông báo ngữ cảnh mẫu sau:

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

Xin lưu ý rằng mặc dù các phần nội dung có thể thuộc loại functionResponse, nhưng bạn không nên sử dụng BidiGenerateContentClientContent để cung cấp phản hồi cho các lệnh gọi hàm do mô hình đưa ra. Bạn nên chuyển sang dùng BidiGenerateContentToolResponse. Bạn chỉ nên sử dụng BidiGenerateContentClientContent để thiết lập ngữ cảnh trước đó hoặc cung cấp dữ liệu đầu vào văn bản cho cuộc trò chuyện.

Truyền trực tuyến âm thanh và video

Lệnh gọi hàm

Tất cả các hàm phải được khai báo ở đầu phiên bằng cách gửi định nghĩa công cụ trong thông báo BidiGenerateContentSetup.

Hãy xem Hướng dẫn gọi hàm để tìm hiểu thêm về cách gọi hàm.

Từ một câu lệnh duy nhất, mô hình có thể tạo nhiều lệnh gọi hàm và mã cần thiết để tạo chuỗi đầu ra. Mã này thực thi trong môi trường hộp cát, tạo ra các thông báo BidiGenerateContentToolCall tiếp theo. Quá trình thực thi sẽ tạm dừng cho đến khi có kết quả của từng lệnh gọi hàm, đảm bảo quá trình xử lý tuần tự.

Ứng dụng sẽ phản hồi bằng BidiGenerateContentToolResponse.

Đầu vào âm thanh và đầu ra âm thanh ảnh hưởng tiêu cực đến khả năng của mô hình trong việc sử dụng lệnh gọi hàm.

Định dạng âm thanh

API Trực tiếp đa phương thức hỗ trợ các định dạng âm thanh sau:

• Định dạng âm thanh đầu vào: Âm thanh PCM 16 bit thô ở 16 kHz little-endian
• Định dạng âm thanh đầu ra: Âm thanh PCM 16 bit thô ở 24 kHz little-endian

Hướng dẫn về hệ thống

Bạn có thể cung cấp hướng dẫn hệ thống để kiểm soát tốt hơn đầu ra của mô hình và chỉ định giọng điệu cũng như cảm xúc của câu trả lời bằng âm thanh.

Hướng dẫn của hệ thống được thêm vào lời nhắc trước khi tương tác bắt đầu và vẫn có hiệu lực trong toàn bộ phiên.

Bạn chỉ có thể đặt hướng dẫn hệ thống ở đầu phiên, ngay sau khi kết nối ban đầu. Để cung cấp thêm dữ liệu đầu vào cho mô hình trong phiên, hãy sử dụng tính năng cập nhật nội dung gia tăng.

Gián đoạn

Người dùng có thể làm gián đoạn đầu ra của mô hình bất cứ lúc nào. Khi tính năng Phát hiện hoạt động thoại (VAD) phát hiện thấy một sự gián đoạn, quá trình tạo đang diễn ra sẽ bị huỷ và bị loại bỏ. Chỉ thông tin đã gửi đến ứng dụng mới được giữ lại trong nhật ký phiên. Sau đó, máy chủ sẽ gửi một thông báo BidiGenerateContentServerContent để báo cáo sự gián đoạn.

Ngoài ra, máy chủ Gemini sẽ loại bỏ mọi lệnh gọi hàm đang chờ xử lý và gửi thông báo BidiGenerateContentServerContent có mã nhận dạng của các lệnh gọi đã bị huỷ.

Giọng nói

Multimodal Live API hỗ trợ các giọng nói sau: Aoede, Charon, Fenrir, Kore và Puck.

Để chỉ định giọng nói, hãy đặt voice_name trong đối tượng speech_config, trong cấu hình phiên.

Xem nội dung đại diện JSON sau đây của đối tượng speech_config:

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

Các điểm hạn chế

Hãy cân nhắc các giới hạn sau đây của API Trực tiếp đa phương thức và Gemini 2.0 khi bạn lên kế hoạch cho dự án.

Xác thực ứng dụng

API trực tiếp đa phương thức chỉ cung cấp tính năng xác thực máy chủ với máy chủ và không nên dùng cho ứng dụng khách trực tiếp. Dữ liệu đầu vào của ứng dụng khách phải được định tuyến thông qua một máy chủ ứng dụng trung gian để xác thực an toàn bằng API trực tiếp đa phương thức.

Đối với ứng dụng web và ứng dụng di động, bạn nên sử dụng tính năng tích hợp của các đối tác của chúng tôi tại Daily.

Lịch sử cuộc trò chuyện

Mặc dù mô hình này theo dõi các lượt tương tác trong phiên, nhưng nhật ký trò chuyện sẽ không được lưu trữ. Khi một phiên kết thúc, ngữ cảnh tương ứng sẽ bị xoá.

Để khôi phục một phiên trước đó hoặc cung cấp cho mô hình ngữ cảnh trước đây về các lượt tương tác của người dùng, ứng dụng phải duy trì nhật ký trò chuyện của riêng mình và sử dụng thông báo BidiGenerateContentClientContent để gửi thông tin này khi bắt đầu một phiên mới.

Thời lượng phiên tối đa

Thời lượng phiên được giới hạn ở tối đa 15 phút đối với âm thanh hoặc tối đa 2 phút đối với âm thanh và video. Khi thời lượng phiên vượt quá giới hạn, kết nối sẽ bị chấm dứt.

Mô hình cũng bị giới hạn bởi kích thước ngữ cảnh. Việc gửi các phần nội dung lớn cùng với luồng video và âm thanh có thể khiến phiên kết thúc sớm hơn.

Phát hiện hoạt động giọng nói (VAD)

Mô hình này tự động thực hiện tính năng phát hiện hoạt động giọng nói (VAD) trên một luồng đầu vào âm thanh liên tục. VAD luôn bật và không thể định cấu hình các thông số của nó.

Số lượng mã thông báo

Không hỗ trợ số lượng mã thông báo.

Giới hạn số lượng yêu cầu

Các giới hạn tốc độ sau đây sẽ được áp dụng:

• 3 phiên đồng thời cho mỗi khoá API
• 4 triệu mã thông báo mỗi phút

Tin nhắn và sự kiện

Thông tin khác về các loại phổ biến

Để biết thêm thông tin về các loại tài nguyên API thường dùng Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata và Tool, hãy xem phần Tạo nội dung.