#

大模型游戏互动接入(Android)

在支持AI互动的游戏当中，用户可以通过语音或者文字与大模型AI玩家进行互动
互动的前提是游戏中至少得有一个真人，再通过相应接口先加入大模型AI玩家，后续通过ISudAiAgent相关接口和大模型AI玩家进行互动

ISudAiAgent接口

public interface ISudAiAgent {

    /**
     * 进行语音对话时，通过此接口发送语音数据，非必须实现
     * 传入的音频切片是从RTC或系统录音当中获取的PCM数据
     * PCM数据格式必须是：采样率：16000， 采样位数：16， 声道数： MONO
     * PCM数据长度可以根据效果调整，长度大: 精确度好但延时长  长度小：延时短但牺牲精确度
     */
    void pushAudio(ByteBuffer data, int dataLength);

    /** 发送文本内容 */
    void sendText(String text);

    /** 暂停语音识别，暂时不调用pushAudio了 */
    void pauseAudio();

    /** 关闭语音识别 */
    void stopAudio();

    /** 设置回调 */
    void setISudListenerAiAgent(ISudListenerAiAgent listener);
}

一、获取ISudAiAgent

加载游戏后通过ISudFSTAPP接口方法getAiAgent获取ISudAiAgent
在demo中，可通过BaseGameViewModel定义的方法getAiAgent来获取ISudAiAgent 获取ISudAiAgent接口后，可通过该接口和大模型AI玩家进行语音、文字的互动，并可设置监听来接收大模型AI玩家的回复消息

使用样例

public class QuickStartGameViewModel extends BaseGameViewModel {
    @Override
    public void onGameStarted() {
        super.onGameStarted();
        // 在onGameStarted触发之后去拿，可以保证返回对象不为空
        ISudAiAgent aiAgent = getAiAgent();
    }
}

二、添加大模型AI玩家

接口定义文档：通用状态 notifyStateChange

52. 设置游戏中的大模型AI玩家
app_common_game_add_big_scale_model_ai_players

在游戏位当中至少有一个真人时，客户端可通过该接口定义的协议格式向游戏发送消息来添加大模型AI玩家

// 在Demo/QuickStartActivity当中可这样调，用于添加大模型AI玩家
SudGIPAPPState.APPCommonGameAddBigScaleModelAIPlayers aiPlayers = new SudGIPAPPState.APPCommonGameAddBigScaleModelAIPlayers();
aiPlayers.aiPlayers = new ArrayList<>();
SudGIPAPPState.ModelAIPlayers modelAIPlayers = new SudGIPAPPState.ModelAIPlayers();
modelAIPlayers.userId = "userId";
modelAIPlayers.avatar = "avatar";
modelAIPlayers.name = "name";
modelAIPlayers.gender = "male";
modelAIPlayers.aiIdStr = "1";
aiPlayers.aiPlayers.add(modelAIPlayers); // 一次可设置一个或多个
gameViewModel.notifyStateChange(SudGIPAPPState.APP_COMMON_GAME_ADD_BIG_SCALE_MODEL_AI_PLAYERS, aiPlayers);

三、文本对话

APP可选择向游戏发送文本消息与大模型AI玩家对话
通过ISudAiAgent接口方法sendText来向游戏发送文本内容

public interface ISudAiAgent {
    ...
    /** 发送文本内容 */
    void sendText(String text);
    ...
}

// 在Demo/QuickStartActivity当中可这样调，用于向游戏发送文本消息
ISudAiAgent aiAgent = gameViewModel.getAiAgent();
if (aiAgent != null) {
    aiAgent.sendText("text");
}

四、语音对话

APP可选择向游戏发送语音消息与大模型AI玩家对话
通过ISudAiAgent接口方法pushAudio来向游戏发送语音消息
pauseAudio用于暂停语音对话，stopAudio用于关闭语音对话

public interface ISudAiAgent {
    ...
    /**
     * 进行语音对话时，通过此接口发送语音数据，非必须实现
     * 传入的音频切片是从RTC或系统录音当中获取的PCM数据
     * PCM数据格式必须是：采样率：16000， 采样位数：16， 声道数： MONO
     * PCM数据长度可以根据效果调整，长度大: 精确度好但延时长  长度小：延时短但牺牲精确度
     */
    void pushAudio(ByteBuffer data, int dataLength);

    /** 暂停语音识别，暂时不调用pushAudio了 */
    void pauseAudio();

    /** 关闭语音识别 */
    void stopAudio();
    ...
}

// 在Demo/QuickStartActivity当中可这样调，用于向游戏发送语音数据
ISudAiAgent aiAgent = gameViewModel.getAiAgent();
if (aiAgent != null) {
    aiAgent.pushAudio(data, dataLength);
}

五、接收大模型AI玩家的消息

当APP通过语音或者文字向大模型AI玩家发送消息之后，大模型AI玩家会进行回复一条或多条消息给房间里的玩家
通过ISudAiAgent接口方法setISudListenerAiAgent设置监听器用于监听大模型AI玩家的回复消息

public interface ISudAiAgent {
    ...
    /** 设置回调 */
    void setISudListenerAiAgent(ISudListenerAiAgent listener);
    ...
}

public interface ISudListenerAiAgent {
    /** 大模型AI消息 */
    void onRoomChatMessage(String json);
}

// ISudListenerAiAgent.onRoomChatMessage返回的json格式
{
    "uid": "26", // 大模型AI玩家的uid
    "content": "我是双子座哦，你们呢？", // 大模型AI玩家说话的文本内容，和语音是对应的
    "audioData": "base64格式的音频数据" // 大模型AI玩家说话的语音内容，和文本是对应的
}

// 在Demo/QuickStartGameViewModel当中可这样调，用于监听大模型AI玩家发送过来的消息
public class QuickStartGameViewModel extends BaseGameViewModel {
    @Override
    public void onGameStarted() {
        super.onGameStarted();
        // 在onGameStarted触发之后去拿，可以保证返回对象不为空
        ISudAiAgent aiAgent = getAiAgent();
        aiAgent.setISudListenerAiAgent(new ISudListenerAiAgent() {
            @Override
            public void onRoomChatMessage(String json) {
                try {
                    JSONObject obj = new JSONObject(json);
                    String audioData = obj.getString("audioData"); // base64格式的音频数据，将其通过Base64解成字节数组之后，就是mp3格式的二进制音频数据了，可参考demo代码进行播放
                    String uid = obj.getString("uid"); // 大模型AI玩家的uid
                    String content = obj.getString("content"); // 文本内容，和语音说话出来的内容是对应的，可根据自身产品需求决定是否展示
                    playAudioData(uid, audioData);
                } catch (Exception e) {
                    e.printStackTrace();
                }                
            }
        });
    }
}

当收到onRoomChatMessage回调时，大型型AI玩家的说话内容，APP根据自身产品需求来选择展示文本消息或者是播放语音消息

六、声浪控制

当APP收到下面的游戏消息时，表示APP可选择控制游戏展示对应玩家的声浪效果
接口定义文档：通用状态-游戏

69. 通知app可以开始推送麦克说话状态
mg_common_game_player_mic_state

收到指令之后可通过如下接口进行控制
接口定义文档：通用状态 notifyStateChange

51. app向游戏下发玩家mic状态
app_common_game_player_mic_state

用于控制游戏当中是否显示指定玩家的声浪，是一个开关性质的指令，开启或关闭的时候发送一次即可

// 在Demo/QuickStartGameViewModel当中可这样调，用于控制游戏声浪展示
public class QuickStartGameViewModel extends BaseGameViewModel {
    @Override
    public void onGameMGCommonGamePlayerMicState(ISudFSMStateHandle handle, SudGIPMGState.MGCommonGamePlayerMicState model) {
        super.onGameMGCommonGamePlayerMicState(handle, model);
        // 收到这个回调之后，游戏销毁之前，都可以通过以下样例所示的方式来控制声浪展示
        SudGIPAPPState.AppCommonGamePlayerMicState micState = new SudGIPAPPState.AppCommonGamePlayerMicState();
        micState.uid = "userId";
        micState.state = 1; // 0：停止说话 1：说话中
        notifyStateChange(SudGIPAPPState.APP_COMMON_GAME_PLAYER_MIC_STATE, micState);
    }
}