管理 Live API 的工作階段

Gemini Live API 會處理稱為「工作階段」的連續音訊或文字串流。您可以管理工作階段生命週期，從初始信號交換到正常終止。

工作階段限制

對於 Live API，工作階段是指持續連線，輸入和輸出內容會透過同一連線持續串流。

如果工作階段超出任何下列限制，連線就會終止。

  • 連線時間長度限制為 10 分鐘左右。

  • 工作階段長度取決於輸入模式：

    • 純音訊輸入工作階段的時間上限為 15 分鐘。
    • 影片和音訊輸入內容的長度上限為 2 分鐘。

  • 工作階段脈絡窗口最多可容納 12.8 萬個權杖。

連線結束前，您會收到即將結束通知，以便採取進一步行動。

開始練習

請參閱入門指南，瞭解如何啟動工作階段的完整程式碼片段。Live API

在工作階段中更新

Live API 模型支援下列進階功能，可進行工作階段中更新：

新增增量內容更新

您可以在進行中的工作階段新增增量更新。可用於傳送文字輸入內容、建立工作階段脈絡或還原工作階段脈絡。

  • 如要提供較長的背景資訊，建議您提供單一訊息摘要，為後續互動釋出背景資訊視窗。

  • 如果是簡短的內容，您可以傳送逐輪互動，代表確切的事件順序，如下方程式碼片段所示。

Swift 

// Define initial turns (history/context).
let turns: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of France?")]),
  ModelContent(role: "model", parts: [TextPart("Paris")]),
]

// Send history, keeping the conversational turn OPEN (false).
await session.sendContent(turns, turnComplete: false)

// Define the new user query.
let newTurn: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of Germany?")]),
]

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.sendContent(newTurn, turnComplete: true)

Kotlin 

Not yet supported for Android apps - check back soon!

Java 

Not yet supported for Android apps - check back soon!

Web 

const turns = [{ text: "Hello from the user!" }];

await session.send(
  turns,
  false // turnComplete: false
);

console.log("Sent history. Waiting for next input...");

// Define the new user query.
const newTurn [{ text: "And what is the capital of Germany?" }];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
    newTurn,
    true // turnComplete: true
);
console.log("Sent final query. Model response expected now.");

Dart 

// Define initial turns (history/context).
final List turns = [
  Content(
    "user",
    [Part.text("What is the capital of France?")],
  ),
  Content(
    "model",
    [Part.text("Paris")],
  ),
];

// Send history, keeping the conversational turn OPEN (false).
await session.send(
  input: turns,
  turnComplete: false,
);

// Define the new user query.
final List newTurn = [
  Content(
    "user",
    [Part.text("What is the capital of Germany?")],
  ),
];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
  input: newTurn,
  turnComplete: true,
);

Unity 

// Define initial turns (history/context).
List turns = new List {
    new ModelContent("user", new ModelContent.TextPart("What is the capital of France?") ),
    new ModelContent("model", new ModelContent.TextPart("Paris") ),
};

// Send history, keeping the conversational turn OPEN (false).
foreach (ModelContent turn in turns)
{
    await session.SendAsync(
        content: turn,
        turnComplete: false
    );
}

// Define the new user query.
ModelContent newTurn = ModelContent.Text("What is the capital of Germany?");

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.SendAsync(
    content: newTurn,
    turnComplete: true
);

在工作階段中更新系統指令

只有在使用 Vertex AI Gemini API 做為 API 供應商時，才能使用這項功能。

在工作階段進行期間，你可以更新系統指示。您可以使用這項功能調整模型的回覆，例如變更回覆語言或修改語氣。

如要在工作階段中更新系統指令，可以傳送具有 system 角色的文字內容。更新後的系統指令會在工作階段的其餘時間內生效。

Swift 

await session.sendContent(
  [ModelContent(
    role: "system",
    parts: [TextPart("new system instruction")]
  )],
  turnComplete: false
)

Kotlin 

Not yet supported for Android apps - check back soon!

Java 

Not yet supported for Android apps - check back soon!

Web 

Not yet supported for Web apps - check back soon!

Dart 

try {
  await _session.send(
    input: Content(
      'system',
      [Part.text('new system instruction')],
    ),
    turnComplete: false,
  );
} catch (e) {
  print('Failed to update system instructions: $e');
}

Unity 

try
{
    await session.SendAsync(
        content: new ModelContent(
            "system",
            new ModelContent.TextPart("new system instruction")
        ),
        turnComplete: false
    );
}
catch (Exception e)
{
    Debug.LogError($"Failed to update system instructions: {e.Message}");
}

偵測工作階段何時結束

工作階段結束前 60 秒，系統會向用戶端傳送即將結束通知，讓您採取進一步行動。

以下範例說明如何監聽「going away」通知，偵測即將終止的會話：

Swift 

for try await response in session.responses {
  switch response.payload {

  case .goingAwayNotice(let goingAwayNotice):
    // Prepare for the session to close soon
    if let timeLeft = goingAwayNotice.timeLeft {
        print("Server going away in \(timeLeft) seconds")
    }
  }
}

Kotlin 

for (response in session.responses) {
    when (val message = response.payload) {
        is LiveServerGoAway -> {
            // Prepare for the session to close soon
            val remaining = message.timeLeft
            logger.info("Server going away in $remaining")
        }
    }
}

Java 

session.getResponses().forEach(response -> {
    if (response.getPayload() instanceof LiveServerResponse.GoingAwayNotice) {
        LiveServerResponse.GoingAwayNotice notice = (LiveServerResponse.GoingAwayNotice) response.getPayload();
        // Prepare for the session to close soon
        Duration timeLeft = notice.getTimeLeft();
    }
});

Web 

for await (const message of session.receive()) {
  switch (message.type) {

  ...
  case "goingAwayNotice":
    console.log("Server going away. Time left:", message.timeLeft);
    break;
  }
}

Dart 

Future _handleLiveServerMessage(LiveServerResponse response) async {
  final message = response.message;
  if (message is GoingAwayNotice) {
     // Prepare for the session to close soon
     developer.log('Server going away. Time left: ${message.timeLeft}');
  }
}

Unity 

foreach (var response in session.Responses) {
    if (response.Payload is LiveSessionGoingAway notice) {
        // Prepare for the session to close soon
        TimeSpan timeLeft = notice.TimeLeft;
        Debug.Log($"Server going away notice received. Remaining: {timeLeft}");
    }
}