Google Gemini多模态API中系统指令的正确使用方式

在使用Google Gemini的多模态实时API开发过程中，许多开发者可能会遇到一个常见问题：当尝试通过ClientContentMessage发送带有"system"角色的消息时，连接会意外关闭。本文将深入探讨这一现象背后的原因，并介绍正确的系统指令使用方法。

问题现象分析

开发者通常会尝试以下方式发送系统指令：

const clientContentRequest: ClientContentMessage = {
    clientContent: {
        turns: [
            {
                role: "system",  // 这里使用了system角色
                parts: [
                    {
                        text: "Greet the user!!",
                    },
                ],
            },
        ],
        turnComplete: true,
    },
};
client._sendDirect(clientContentRequest);

执行上述代码会导致连接关闭，并收到"Request contains an invalid argument"的错误提示。而如果将角色改为"user"，同样的代码却能正常工作。

根本原因

经过官方确认，这是API的预期行为。Gemini API在设计上对系统指令的使用有明确的规范：

1. 系统指令必须通过配置设置：系统级别的指令不应通过常规的消息流发送，而应在初始化配置中指定。

2. 消息角色限制：在ClientContentMessage中，role字段只能接受"user"或"model"两种值，分别代表用户输入和模型响应。

正确实践方案

要正确设置系统指令，开发者应该：

1. 在初始化配置中设置systemInstruction：这是唯一被支持的系统指令设置方式。

2. 遵循消息角色规范：在对话流中，严格使用"user"表示用户输入，"model"表示AI响应。

// 正确的系统指令设置方式（示例）
const config = {
    systemInstruction: {
        parts: [
            {
                text: "你是一个友好的助手，请用中文回答用户问题。",
            },
        ],
    },
    // 其他配置参数...
};

开发者注意事项

1. API行为变更：值得注意的是，早期版本可能允许通过消息流发送系统指令，但最新版本已明确禁止这种做法。

2. 错误处理：当遇到"Request contains an invalid argument"错误时，应首先检查是否有违规使用"system"角色的情况。

3. 设计理念理解：这种设计有助于区分一次性系统指令和持续对话内容，使API使用更加规范和安全。

通过遵循这些最佳实践，开发者可以避免连接意外关闭的问题，并充分利用Gemini多模态API的强大功能。