Live API - WebSockets API reference

Live API là một API có trạng thái sử dụng WebSockets. Trong phần này, bạn sẽ tìm thấy thông tin chi tiết bổ sung về API WebSockets.

Phiên

Kết nối WebSocket thiết lập một phiên giữa ứng dụng và máy chủ Gemini. Sau khi một ứng dụng bắt đầu một kết nối mới, phiên này 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 yêu cầu về âm thanh, văn bản hoặc lệnh gọi hàm từ máy chủ Gemini.

Kết nối WebSocket

Để bắt đầu một phiên, hãy kết nối với điểm cuối websocket này:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Cấu hình phiên

Thông báo ban đầu được gửi sau khi thiết lập kết nối WebSocket sẽ đặt cấu hình phiên, bao gồm mô hình, các tham số tạo, hướng dẫn hệ thống và công cụ.

Bạn không thể cập nhật cấu hình khi kết nối đang mở. Tuy nhiên, bạn có thể thay đổi các thông số cấu hình, ngoại trừ mô hình, khi tạm dừng và tiếp tục thông qua cơ chế tiếp tục phiên.

Hãy xem cấu hình ví dụ sau đây. Xin lưu ý rằng cách viết hoa tên trong SDK có thể khác nhau. Bạn có thể tra cứu các lựa chọn cấu hình Python SDK tại đây.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object
  },
  "systemInstruction": string,
  "tools": [object]
}

Để biết thêm thông tin về trường API, hãy xem generationConfig.

Gửi tin nhắn

Để trao đổi thông báo qua kết nối WebSocket, máy khách phải gửi một đối tượng JSON qua kết nối WebSocket đang mở. Đối tượng JSON phải có chính xác một trong số các trường của tập hợp đối tượng sau:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Tin nhắn được hỗ trợ của khách hàng

Hãy xem các thông báo được hỗ trợ của ứng dụng trong bảng sau:

Nhắn tin	Mô tả
`BidiGenerateContentSetup`	Cấu hình phiên sẽ được gửi trong thư đầu tiên
`BidiGenerateContentClientContent`	Bản cập nhật nội dung gia tăng của cuộc trò chuyện hiện tại được gửi từ ứng dụng
`BidiGenerateContentRealtimeInput`	Nhập âm thanh, video hoặc văn bản theo thời gian thực
`BidiGenerateContentToolResponse`	Phản hồi cho `ToolCallMessage` nhận được từ máy chủ

Nhận tin nhắn

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

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

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Thông báo của máy chủ có thể có trường usageMetadata nhưng sẽ bao gồm chính xác một trong số các trường khác từ thông báo BidiGenerateContentServerMessage. (Hợp nhất messageType không được biểu thị trong JSON nên trường này sẽ xuất hiện ở cấp cao nhất của thông báo.)

Tin nhắn và sự kiện

ActivityEnd

Loại này không có trường nào.

Đánh dấu thời điểm kết thúc hoạt động của người dùng.

ActivityHandling

Các cách xử lý hoạt động của người dùng.

Enum
`ACTIVITY_HANDLING_UNSPECIFIED`	Nếu bạn không chỉ định, hành vi mặc định sẽ là `START_OF_ACTIVITY_INTERRUPTS`.
`START_OF_ACTIVITY_INTERRUPTS`	Nếu đúng, hoạt động bắt đầu sẽ làm gián đoạn phản hồi của mô hình (còn gọi là "barge in"). Câu trả lời hiện tại của mô hình sẽ bị cắt ngang ngay khi có yêu cầu mới. Đây là hành vi mặc định.
`NO_INTERRUPTION`	Câu trả lời của mô hình sẽ không bị gián đoạn.

ActivityStart

Loại này không có trường nào.

Đánh dấu thời điểm bắt đầu hoạt động của người dùng.

AudioTranscriptionConfig

Loại này không có trường nào.

Cấu hình bản chép lời.

AutomaticActivityDetection

Định cấu hình tính năng tự động phát hiện hoạt động.

Trường
`disabled`	`bool` Không bắt buộc. Nếu được bật (mặc định), thì giọng nói và văn bản đã phát hiện được sẽ được tính là hoạt động. Nếu bị vô hiệu hoá, ứng dụng phải gửi tín hiệu hoạt động.
`startOfSpeechSensitivity`	`StartSensitivity` Không bắt buộc. Xác định khả năng phát hiện lời nói.
`prefixPaddingMs`	`int32` Không bắt buộc. Thời lượng bắt buộc của lời nói được phát hiện trước khi bắt đầu lời nói được cam kết. Giá trị này càng thấp thì tính năng phát hiện bắt đầu lời nói càng nhạy và lời nói càng ngắn thì càng được nhận dạng. Tuy nhiên, điều này cũng làm tăng khả năng có kết quả dương tính giả.
`endOfSpeechSensitivity`	`EndSensitivity` Không bắt buộc. Xác định khả năng lời nói được phát hiện đã kết thúc.
`silenceDurationMs`	`int32` Không bắt buộc. Thời lượng bắt buộc của đoạn không phải lời nói được phát hiện (ví dụ: khoảng lặng) trước khi kết thúc lời nói được xác nhận. Giá trị này càng lớn thì khoảng trống trong lời nói càng dài mà không làm gián đoạn hoạt động của người dùng, nhưng điều này sẽ làm tăng độ trễ của mô hình.

BidiGenerateContentClientContent

Bản cập nhật gia tăng của cuộc trò chuyện hiện tại được gửi từ ứng dụng. Tất cả nội dung ở đây đều được thêm vô điều kiện vào nhật ký trò chuyện và được dùng làm một phần của câu lệnh cho mô hình để tạo nội dung.

Thông báo tại đây sẽ làm gián đoạn mọi hoạt động tạo mô hình hiện tại.

Trường

Trường
`turns[]`	`Content` Không bắt buộc. Nội dung được thêm vào cuộc trò chuyện hiện tại với mô hình. Đối với các cụm từ tìm kiếm một lượt, đây là một phiên bản duy nhất. Đối với các cụm từ tìm kiếm nhiều lượt, đây là một trường lặp lại chứa nhật ký trò chuyện và yêu cầu mới nhất.
`turnComplete`	`bool` Không bắt buộc. Nếu đúng, tức là quá trình tạo nội dung trên máy chủ sẽ bắt đầu bằng câu lệnh hiện đang được tích luỹ. Nếu không, máy chủ sẽ chờ thêm các thông báo khác trước khi bắt đầu tạo.

turns[]

Content

Không bắt buộc. Nội dung được thêm vào cuộc trò chuyện hiện tại với mô hình.

Đối với các cụm từ tìm kiếm một lượt, đây là một phiên bản duy nhất. Đối với các cụm từ tìm kiếm nhiều lượt, đây là một trường lặp lại chứa nhật ký trò chuyện và yêu cầu mới nhất.

turnComplete

bool

Không bắt buộc. Nếu đúng, tức là quá trình tạo nội dung trên máy chủ sẽ bắt đầu bằng câu lệnh hiện đang được tích luỹ. Nếu không, máy chủ sẽ chờ thêm các thông báo khác trước khi bắt đầu tạo.

BidiGenerateContentRealtimeInput

Dữ liệu đầu vào của người dùng được gửi theo thời gian thực.

Các phương thức (âm thanh, video và văn bản) được xử lý dưới dạng các luồng đồng thời. Chúng tôi không đảm bảo thứ tự của các luồng này.

Lệnh này khác với BidiGenerateContentClientContent ở một số điểm:

Có thể được gửi liên tục mà không bị gián đoạn quá trình tạo mô hình.
Nếu cần kết hợp dữ liệu xen kẽ trên BidiGenerateContentClientContent và BidiGenerateContentRealtimeInput, thì máy chủ sẽ cố gắng tối ưu hoá để có phản hồi tốt nhất, nhưng không có gì đảm bảo.
Không chỉ định rõ điểm kết thúc lượt, mà được suy ra từ hoạt động của người dùng (ví dụ: kết thúc lời nói).
Ngay cả trước khi kết thúc lượt, dữ liệu sẽ được xử lý tăng dần để tối ưu hoá cho việc bắt đầu phản hồi nhanh từ mô hình.

Trường
`mediaChunks[]`	`Blob` Không bắt buộc. Dữ liệu byte nội tuyến cho đầu vào nội dung nghe nhìn. Nhiều `mediaChunks` không được hỗ trợ, tất cả trừ `mediaChunks` đầu tiên sẽ bị bỏ qua. KHÔNG DÙNG NỮA: Thay vào đó, hãy dùng một trong các tham số `audio`, `video` hoặc `text`.
`audio`	`Blob` Không bắt buộc. Đây là những thành phần tạo nên luồng đầu vào âm thanh theo thời gian thực.
`video`	`Blob` Không bắt buộc. Đây là những thành phần tạo nên luồng đầu vào video theo thời gian thực.
`activityStart`	`ActivityStart` Không bắt buộc. Đánh dấu thời điểm bắt đầu hoạt động của người dùng. Bạn chỉ có thể gửi thông tin này nếu tính năng phát hiện hoạt động tự động (tức là phía máy chủ) bị tắt.
`activityEnd`	`ActivityEnd` Không bắt buộc. Đánh dấu thời điểm kết thúc hoạt động của người dùng. Bạn chỉ có thể gửi thông tin này nếu tính năng phát hiện hoạt động tự động (tức là phía máy chủ) bị tắt.
`audioStreamEnd`	`bool` Không bắt buộc. Cho biết luồng âm thanh đã kết thúc, ví dụ: do micrô đã bị tắt. Bạn chỉ nên gửi thông báo này khi bật tính năng tự động phát hiện hoạt động (theo mặc định). Ứng dụng có thể mở lại luồng bằng cách gửi một tin nhắn âm thanh.
`text`	`string` Không bắt buộc. Đây là luồng nhập văn bản theo thời gian thực.

BidiGenerateContentServerContent

Bản cập nhật máy chủ gia tăng do mô hình tạo ra để phản hồi các thông báo của ứng dụng khách.

Nội dung được tạo nhanh nhất có thể chứ không phải theo thời gian thực. Ứng dụng có thể chọn lưu vào bộ nhớ đệm và phát theo thời gian thực.

Trường
`generationComplete`	`bool` Chỉ có đầu ra. Nếu là true, tức là mô hình đã tạo xong. Khi mô hình bị gián đoạn trong quá trình tạo, sẽ không có thông báo "generation_complete" trong lượt bị gián đoạn, mà sẽ chuyển qua "interrupted > turn_complete". Khi mô hình giả định việc phát theo thời gian thực, sẽ có độ trễ giữa generation_complete và turn_complete do mô hình chờ quá trình phát kết thúc.
`turnComplete`	`bool` Chỉ có đầu ra. Nếu là true, tức là mô hình đã hoàn tất lượt của mình. Quá trình tạo chỉ bắt đầu khi có thêm tin nhắn của khách hàng.
`interrupted`	`bool` Chỉ có đầu ra. Nếu đúng, cho biết rằng một thông báo của ứng dụng đã làm gián đoạn quá trình tạo mô hình hiện tại. Nếu ứng dụng đang phát nội dung theo thời gian thực, thì đây là một tín hiệu tốt để dừng và xoá hàng đợi phát hiện tại.
`groundingMetadata`	`GroundingMetadata` Chỉ có đầu ra. Siêu dữ liệu cơ sở cho nội dung được tạo.
`inputTranscription`	`BidiGenerateContentTranscription` Chỉ có đầu ra. Nhập bản chép lời âm thanh. Bản chép lời được gửi độc lập với các thông báo khác của máy chủ và không có thứ tự đảm bảo.
`outputTranscription`	`BidiGenerateContentTranscription` Chỉ có đầu ra. Xuất bản chép lời âm thanh. Bản chép lời được gửi độc lập với các thông báo khác của máy chủ và không có thứ tự đảm bảo, đặc biệt là giữa `serverContent` và `outputTranscription` này.
`urlContextMetadata`	`UrlContextMetadata`
`modelTurn`	`Content` Chỉ có đầu ra. Nội dung mà mô hình đã tạo trong cuộc trò chuyện hiện tại với người dùng.

BidiGenerateContentServerMessage

Thông báo phản hồi cho lệnh gọi BidiGenerateContent.

Trường
`usageMetadata`	`UsageMetadata` Chỉ có đầu ra. Siêu dữ liệu về mức sử dụng đối với(các) câu trả lời.
Trường nhóm `messageType`. Loại thông báo. `messageType` chỉ có thể là một trong những trạng thái sau:
`setupComplete`	`BidiGenerateContentSetupComplete` Chỉ có đầu ra. Được gửi để phản hồi tin nhắn `BidiGenerateContentSetup` của ứng dụng khi quá trình thiết lập hoàn tất.
`serverContent`	`BidiGenerateContentServerContent` Chỉ có đầu ra. Nội dung do mô hình tạo để phản hồi tin nhắn của khách hàng.
`toolCall`	`BidiGenerateContentToolCall` Chỉ có đầu ra. Yêu cầu ứng dụng khách thực thi `functionCalls` và trả về các phản hồi có `id` tương ứng.
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` Chỉ có đầu ra. Thông báo cho ứng dụng rằng `ToolCallMessage` đã phát hành trước đó với `id` được chỉ định sẽ bị huỷ.
`goAway`	`GoAway` Chỉ có đầu ra. Thông báo cho biết máy chủ sắp ngắt kết nối.
`sessionResumptionUpdate`	`SessionResumptionUpdate` Chỉ có đầu ra. Cập nhật trạng thái tiếp tục phiên.

BidiGenerateContentSetup

Tin nhắn sẽ được gửi trong BidiGenerateContentClientMessage đầu tiên (và chỉ trong BidiGenerateContentClientMessage đầu tiên). Chứa cấu hình sẽ áp dụng trong suốt thời gian của RPC truyền phát trực tiếp.

Ứng dụng nên đợi thông báo BidiGenerateContentSetupComplete trước khi gửi thêm thông báo.

Trường
`model`	`string` Bắt buộc. Tên tài nguyên của mô hình. Đây là mã nhận dạng mà Mô hình sẽ sử dụng. Định dạng `models/{model}`
`generationConfig`	`GenerationConfig` Không bắt buộc. Cấu hình tạo. Các trường sau không được hỗ trợ: `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` Không bắt buộc. Người dùng đã cung cấp hướng dẫn hệ thống cho mô hình. Lưu ý: Bạn chỉ nên sử dụng văn bản trong các phần và nội dung trong mỗi phần sẽ nằm trong một đoạn văn riêng.
`tools[]`	`Tool` Không bắt buộc. Danh sách `Tools` mà mô hình có thể dùng để tạo câu trả lời tiếp theo. `Tool` là một đoạn mã cho phép hệ thống tương tác với các hệ thống bên ngoài để thực hiện một hành động hoặc một nhóm hành động nằm ngoài kiến thức và phạm vi của mô hình.
`realtimeInputConfig`	`RealtimeInputConfig` Không bắt buộc. Định cấu hình cách xử lý dữ liệu đầu vào theo thời gian thực.
`sessionResumption`	`SessionResumptionConfig` Không bắt buộc. Định cấu hình cơ chế tiếp tục phiên. Nếu có, máy chủ sẽ gửi thông báo `SessionResumptionUpdate`.
`contextWindowCompression`	`ContextWindowCompressionConfig` Không bắt buộc. Định cấu hình cơ chế nén cửa sổ ngữ cảnh. Nếu được đưa vào, máy chủ sẽ tự động giảm kích thước của ngữ cảnh khi ngữ cảnh vượt quá độ dài đã định cấu hình.
`inputAudioTranscription`	`AudioTranscriptionConfig` Không bắt buộc. Nếu được đặt, chế độ này sẽ bật tính năng chép lời nội dung nhập bằng giọng nói. Bản chép lời sẽ khớp với ngôn ngữ âm thanh đầu vào (nếu được định cấu hình).
`outputAudioTranscription`	`AudioTranscriptionConfig` Không bắt buộc. Nếu được đặt, sẽ bật tính năng chép lời đầu ra âm thanh của mô hình. Bản chép lời sẽ khớp với mã ngôn ngữ được chỉ định cho âm thanh đầu ra (nếu được định cấu hình).
`proactivity`	`ProactivityConfig` Không bắt buộc. Định cấu hình tính chủ động của mô hình. Điều này cho phép mô hình chủ động phản hồi thông tin đầu vào và bỏ qua thông tin đầu vào không liên quan.

BidiGenerateContentSetupComplete

Loại này không có trường nào.

Được gửi để phản hồi tin nhắn BidiGenerateContentSetup của ứng dụng khách.

BidiGenerateContentToolCall

Yêu cầu ứng dụng khách thực thi functionCalls và trả về các phản hồi có id tương ứng.

Trường

Trường
`functionCalls[]`	`FunctionCall` Chỉ có đầu ra. Lệnh gọi hàm sẽ được thực thi.

functionCalls[]

FunctionCall

Chỉ có đầu ra. Lệnh gọi hàm sẽ được thực thi.

BidiGenerateContentToolCallCancellation

Thông báo cho ứng dụng khách rằng một ToolCallMessage đã phát hành trước đó với id được chỉ định không được thực thi và phải bị huỷ. Nếu có tác dụng phụ đối với những lệnh gọi công cụ đó, thì các ứng dụng có thể cố gắng huỷ lệnh gọi công cụ. Thông báo này chỉ xuất hiện trong trường hợp các ứng dụng gián đoạn lượt phản hồi của máy chủ.

Trường

Trường
`ids[]`	`string` Chỉ có đầu ra. Mã nhận dạng của các lệnh gọi công cụ cần huỷ.

ids[]

string

Chỉ có đầu ra. Mã nhận dạng của các lệnh gọi công cụ cần huỷ.

BidiGenerateContentToolResponse

Phản hồi do ứng dụng tạo cho một ToolCall nhận được từ máy chủ. Các đối tượng FunctionResponse riêng lẻ được so khớp với các đối tượng FunctionCall tương ứng theo trường id.

Xin lưu ý rằng trong các API GenerateContent đơn phương và truyền trực tuyến từ máy chủ, việc gọi hàm diễn ra bằng cách trao đổi các phần Content, trong khi trong các API GenerateContent hai chiều, việc gọi hàm diễn ra thông qua tập hợp thông báo chuyên dụng này.

Trường

Trường
`functionResponses[]`	`FunctionResponse` Không bắt buộc. Phản hồi cho các lệnh gọi hàm.

functionResponses[]

FunctionResponse

Không bắt buộc. Phản hồi cho các lệnh gọi hàm.

BidiGenerateContentTranscription

Chép lời âm thanh (đầu vào hoặc đầu ra).

Trường

Trường
`text`	`string` Văn bản chép lời.

text

string

Văn bản chép lời.

ContextWindowCompressionConfig

Cho phép nén cửa sổ ngữ cảnh – một cơ chế để quản lý cửa sổ ngữ cảnh của mô hình sao cho cửa sổ này không vượt quá một độ dài nhất định.

Trường

Trường
Trường nhóm `compressionMechanism`. Cơ chế nén cửa sổ theo ngữ cảnh được sử dụng. `compressionMechanism` chỉ có thể là một trong những trạng thái sau:
`slidingWindow`	`SlidingWindow` Cơ chế cửa sổ trượt.
`triggerTokens`	`int64` Số lượng mã thông báo (trước khi chạy một lượt) cần thiết để kích hoạt tính năng nén cửa sổ ngữ cảnh. Bạn có thể dùng tham số này để cân bằng chất lượng với độ trễ vì cửa sổ ngữ cảnh ngắn hơn có thể giúp mô hình phản hồi nhanh hơn. Tuy nhiên, mọi thao tác nén sẽ làm tăng độ trễ tạm thời, vì vậy, bạn không nên kích hoạt các thao tác này thường xuyên. Nếu bạn không đặt giá trị này, giá trị mặc định sẽ là 80% giới hạn cửa sổ ngữ cảnh của mô hình. Điều này còn lại 20% cho yêu cầu tiếp theo của người dùng/phản hồi của mô hình.

Trường nhóm compressionMechanism. Cơ chế nén cửa sổ theo ngữ cảnh được sử dụng. compressionMechanism chỉ có thể là một trong những trạng thái sau:

slidingWindow

SlidingWindow

Cơ chế cửa sổ trượt.

triggerTokens

int64

Số lượng mã thông báo (trước khi chạy một lượt) cần thiết để kích hoạt tính năng nén cửa sổ ngữ cảnh.

Bạn có thể dùng tham số này để cân bằng chất lượng với độ trễ vì cửa sổ ngữ cảnh ngắn hơn có thể giúp mô hình phản hồi nhanh hơn. Tuy nhiên, mọi thao tác nén sẽ làm tăng độ trễ tạm thời, vì vậy, bạn không nên kích hoạt các thao tác này thường xuyên.

Nếu bạn không đặt giá trị này, giá trị mặc định sẽ là 80% giới hạn cửa sổ ngữ cảnh của mô hình. Điều này còn lại 20% cho yêu cầu tiếp theo của người dùng/phản hồi của mô hình.

EndSensitivity

Xác định cách phát hiện điểm kết thúc lời nói.

Enum
`END_SENSITIVITY_UNSPECIFIED`	Giá trị mặc định là END_SENSITIVITY_HIGH.
`END_SENSITIVITY_HIGH`	Tính năng tự động phát hiện thường kết thúc lời nói.
`END_SENSITIVITY_LOW`	Tính năng tự động phát hiện ít khi kết thúc lời nói.

GoAway

Thông báo cho biết máy chủ sắp ngắt kết nối.

Trường

Trường
`timeLeft`	`Duration` Thời gian còn lại trước khi kết nối bị chấm dứt ở trạng thái BỊ HUỶ. Thời lượng này sẽ không bao giờ nhỏ hơn mức tối thiểu dành riêng cho từng mô hình. Mức tối thiểu này sẽ được chỉ định cùng với hạn mức cho mô hình.

timeLeft

Duration

Thời gian còn lại trước khi kết nối bị chấm dứt ở trạng thái BỊ HUỶ.

Thời lượng này sẽ không bao giờ nhỏ hơn mức tối thiểu dành riêng cho từng mô hình. Mức tối thiểu này sẽ được chỉ định cùng với hạn mức cho mô hình.

ProactivityConfig

Cấu hình cho các tính năng chủ động.

Trường

Trường
`proactiveAudio`	`bool` Không bắt buộc. Nếu được bật, mô hình có thể từ chối phản hồi câu lệnh cuối cùng. Ví dụ: điều này cho phép mô hình bỏ qua lời nói không phù hợp với ngữ cảnh hoặc giữ im lặng nếu người dùng chưa đưa ra yêu cầu.

proactiveAudio

bool

Không bắt buộc. Nếu được bật, mô hình có thể từ chối phản hồi câu lệnh cuối cùng. Ví dụ: điều này cho phép mô hình bỏ qua lời nói không phù hợp với ngữ cảnh hoặc giữ im lặng nếu người dùng chưa đưa ra yêu cầu.

RealtimeInputConfig

Định cấu hình hành vi nhập liệu theo thời gian thực trong BidiGenerateContent.

Trường

Trường
`automaticActivityDetection`	`AutomaticActivityDetection` Không bắt buộc. Nếu bạn không đặt, thì tính năng tự động phát hiện hoạt động sẽ được bật theo mặc định. Nếu tính năng tự động phát hiện giọng nói bị tắt, thì ứng dụng phải gửi tín hiệu hoạt động.
`activityHandling`	`ActivityHandling` Không bắt buộc. Xác định hiệu ứng của hoạt động.
`turnCoverage`	`TurnCoverage` Không bắt buộc. Xác định những dữ liệu đầu vào được đưa vào lượt của người dùng.

automaticActivityDetection

AutomaticActivityDetection

Không bắt buộc. Nếu bạn không đặt, thì tính năng tự động phát hiện hoạt động sẽ được bật theo mặc định. Nếu tính năng tự động phát hiện giọng nói bị tắt, thì ứng dụng phải gửi tín hiệu hoạt động.

activityHandling

ActivityHandling

Không bắt buộc. Xác định hiệu ứng của hoạt động.

turnCoverage

TurnCoverage

Không bắt buộc. Xác định những dữ liệu đầu vào được đưa vào lượt của người dùng.

SessionResumptionConfig

Cấu hình tiếp tục phiên.

Thông báo này có trong cấu hình phiên dưới dạng BidiGenerateContentSetup.sessionResumption. Nếu được định cấu hình, máy chủ sẽ gửi thông báo SessionResumptionUpdate.

Trường

Trường
`handle`	`string` Xử lý một phiên trước đó. Nếu không có, thì một phiên mới sẽ được tạo. Xử lý phiên đến từ các giá trị `SessionResumptionUpdate.token` trong các kết nối trước đó.

handle

string

Xử lý một phiên trước đó. Nếu không có, thì một phiên mới sẽ được tạo.

Xử lý phiên đến từ các giá trị SessionResumptionUpdate.token trong các kết nối trước đó.

SessionResumptionUpdate

Cập nhật trạng thái tiếp tục phiên.

Chỉ được gửi nếu bạn đặt BidiGenerateContentSetup.sessionResumption.

Trường

Trường
`newHandle`	`string` Xử lý mới đại diện cho một trạng thái có thể tiếp tục. Để trống nếu `resumable`=false.
`resumable`	`bool` True nếu phiên hiện tại có thể tiếp tục tại thời điểm này. Bạn không thể tiếp tục ở một số thời điểm trong phiên. Ví dụ: khi mô hình đang thực thi lệnh gọi hàm hoặc tạo nội dung. Việc tiếp tục phiên (bằng mã thông báo phiên trước) ở trạng thái như vậy sẽ dẫn đến mất một số dữ liệu. Trong những trường hợp này, `newHandle` sẽ trống và `resumable` sẽ là false.

newHandle

string

Xử lý mới đại diện cho một trạng thái có thể tiếp tục. Để trống nếu resumable=false.

resumable

bool

True nếu phiên hiện tại có thể tiếp tục tại thời điểm này.

Bạn không thể tiếp tục ở một số thời điểm trong phiên. Ví dụ: khi mô hình đang thực thi lệnh gọi hàm hoặc tạo nội dung. Việc tiếp tục phiên (bằng mã thông báo phiên trước) ở trạng thái như vậy sẽ dẫn đến mất một số dữ liệu. Trong những trường hợp này, newHandle sẽ trống và resumable sẽ là false.

SlidingWindow

Phương thức SlidingWindow hoạt động bằng cách loại bỏ nội dung ở đầu cửa sổ ngữ cảnh. Ngữ cảnh thu được sẽ luôn bắt đầu từ đầu lượt của vai trò NGƯỜI DÙNG. Hướng dẫn hệ thống và mọi BidiGenerateContentSetup.prefixTurns sẽ luôn nằm ở đầu kết quả.

Trường

Trường
`targetTokens`	`int64` Số lượng mã thông báo mục tiêu cần giữ lại. Giá trị mặc định là trigger_tokens/2. Việc loại bỏ các phần của cửa sổ ngữ cảnh sẽ làm tăng độ trễ tạm thời, vì vậy, bạn nên hiệu chỉnh giá trị này để tránh các thao tác nén thường xuyên.

targetTokens

int64

Số lượng mã thông báo mục tiêu cần giữ lại. Giá trị mặc định là trigger_tokens/2.

Việc loại bỏ các phần của cửa sổ ngữ cảnh sẽ làm tăng độ trễ tạm thời, vì vậy, bạn nên hiệu chỉnh giá trị này để tránh các thao tác nén thường xuyên.

StartSensitivity

Xác định cách phát hiện điểm bắt đầu của lời nói.

Enum
`START_SENSITIVITY_UNSPECIFIED`	Giá trị mặc định là START_SENSITIVITY_HIGH.
`START_SENSITIVITY_HIGH`	Tính năng tự động phát hiện sẽ phát hiện điểm bắt đầu của lời nói thường xuyên hơn.
`START_SENSITIVITY_LOW`	Tính năng phát hiện tự động sẽ ít phát hiện được điểm bắt đầu của lời nói hơn.

TurnCoverage

Các lựa chọn về dữ liệu đầu vào có trong lượt của người dùng.

Enum
`TURN_COVERAGE_UNSPECIFIED`	Nếu bạn không chỉ định, hành vi mặc định sẽ là `TURN_INCLUDES_ONLY_ACTIVITY`.
`TURN_INCLUDES_ONLY_ACTIVITY`	Lượt của người dùng chỉ bao gồm hoạt động kể từ lượt gần nhất, không bao gồm thời gian không hoạt động (ví dụ: không có âm thanh trong luồng âm thanh). Đây là hành vi mặc định.
`TURN_INCLUDES_ALL_INPUT`	Lượt của người dùng bao gồm tất cả dữ liệu đầu vào theo thời gian thực kể từ lượt gần nhất, kể cả thời gian không hoạt động (ví dụ: không có âm thanh trong luồng âm thanh).

UrlContextMetadata

Siêu dữ liệu liên quan đến công cụ truy xuất bối cảnh URL.

Trường

urlMetadata[]

UrlMetadata

Danh sách ngữ cảnh URL.

UsageMetadata

Siêu dữ liệu về việc sử dụng đối với(các) câu trả lời.

Trường
`promptTokenCount`	`int32` Chỉ có đầu ra. Số lượng mã thông báo trong câu lệnh. Khi `cachedContent` được đặt, đây vẫn là tổng kích thước của câu lệnh hiệu quả, tức là bao gồm cả số lượng mã thông báo trong nội dung được lưu vào bộ nhớ đệm.
`cachedContentTokenCount`	`int32` Số lượng mã thông báo trong phần được lưu vào bộ nhớ đệm của câu lệnh (nội dung được lưu vào bộ nhớ đệm)
`responseTokenCount`	`int32` Chỉ có đầu ra. Tổng số mã thông báo trong tất cả các đề xuất phản hồi được tạo.
`toolUsePromptTokenCount`	`int32` Chỉ có đầu ra. Số lượng mã thông báo có trong(các) câu lệnh sử dụng công cụ.
`thoughtsTokenCount`	`int32` Chỉ có đầu ra. Số lượng mã thông báo của suy nghĩ đối với mô hình tư duy.
`totalTokenCount`	`int32` Chỉ có đầu ra. Tổng số mã thông báo cho yêu cầu tạo (lời nhắc + các câu trả lời đề xuất).
`promptTokensDetails[]`	`ModalityTokenCount` Chỉ có đầu ra. Danh sách các phương thức đã được xử lý trong dữ liệu đầu vào của yêu cầu.
`cacheTokensDetails[]`	`ModalityTokenCount` Chỉ có đầu ra. Danh sách các phương thức của nội dung được lưu vào bộ nhớ đệm trong dữ liệu đầu vào của yêu cầu.
`responseTokensDetails[]`	`ModalityTokenCount` Chỉ có đầu ra. Danh sách các phương thức được trả về trong phản hồi.
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` Chỉ có đầu ra. Danh sách các phương thức đã được xử lý cho dữ liệu đầu vào của yêu cầu sử dụng công cụ.

Mã thông báo xác thực tạm thời

Bạn có thể lấy mã thông báo xác thực tạm thời bằng cách gọi AuthTokenService.CreateToken rồi dùng với GenerativeService.BidiGenerateContentConstrained, bằng cách truyền mã thông báo trong tham số truy vấn access_token hoặc trong tiêu đề HTTP Authorization có tiền tố "Token".

CreateAuthTokenRequest

Tạo mã thông báo xác thực tạm thời.

Trường

Trường
`authToken`	`AuthToken` Bắt buộc. Mã thông báo cần tạo.

authToken

AuthToken

Bắt buộc. Mã thông báo cần tạo.

AuthToken

Yêu cầu tạo mã thông báo xác thực tạm thời.

Trường
`name`	`string` Chỉ có đầu ra. Giá trị nhận dạng. Chính mã thông báo.
`expireTime`	`Timestamp` Không bắt buộc. Chỉ có đầu vào. Không thể thay đổi. Thời gian không bắt buộc mà sau đó, khi sử dụng mã thông báo kết quả, các thông báo trong phiên BidiGenerateContent sẽ bị từ chối. (Gemini có thể chủ động đóng phiên sau thời gian này.) Nếu bạn không đặt chính sách này, thì chính sách này sẽ mặc định là 30 phút sau. Nếu được đặt, giá trị này phải nhỏ hơn 20 giờ trong tương lai.
`newSessionExpireTime`	`Timestamp` Không bắt buộc. Chỉ có đầu vào. Không thể thay đổi. Thời gian sau đó các phiên Live API mới sử dụng mã thông báo có được từ yêu cầu này sẽ bị từ chối. Nếu không được đặt, giá trị này sẽ mặc định là 60 giây trong tương lai. Nếu được đặt, giá trị này phải nhỏ hơn 20 giờ trong tương lai.
`fieldMask`	`FieldMask` Không bắt buộc. Chỉ có đầu vào. Không thể thay đổi. Nếu field_mask trống và không có `bidiGenerateContentSetup`, thì thông báo `BidiGenerateContentSetup` có hiệu lực sẽ được lấy từ mối kết nối Live API. Nếu field_mask trống và `bidiGenerateContentSetup` is xuất hiện, thì thông báo `BidiGenerateContentSetup` có hiệu lực sẽ được lấy hoàn toàn từ `bidiGenerateContentSetup` trong yêu cầu này. Thông báo thiết lập từ kết nối Live API sẽ bị bỏ qua. Nếu field_mask không phải là một trường trống, thì các trường tương ứng trong `bidiGenerateContentSetup` sẽ ghi đè các trường trong thông báo thiết lập trong kết nối Live API.
Trường nhóm `config`. Cấu hình dành riêng cho phương thức của mã thông báo kết quả. `config` chỉ có thể là một trong những trạng thái sau:
`bidiGenerateContentSetup`	`BidiGenerateContentSetup` Không bắt buộc. Chỉ có đầu vào. Không thể thay đổi. Cấu hình dành riêng cho `BidiGenerateContent`.
`uses`	`int32` Không bắt buộc. Chỉ có đầu vào. Không thể thay đổi. Số lần có thể sử dụng mã thông báo. Nếu giá trị này bằng 0 thì không có giới hạn nào được áp dụng. Việc tiếp tục một phiên Live API không được tính là một lượt sử dụng. Nếu bạn không chỉ định, giá trị mặc định là 1.

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, ModalityTokenCount và Tool, hãy xem phần Tạo nội dung.