Vocode核心库中ChatGPT动作参数传递问题的分析与解决

在基于Vocode核心库开发语音对话系统时，一个常见的技术挑战是确保ChatGPT代理能够正确地将参数传递给自定义动作(action)。本文将深入分析这一问题的根源，并提供完整的解决方案。

问题现象

开发者在实现一个保存用户数据的自定义动作时发现，虽然ChatGPT代理正确识别了需要触发动作的时机，但动作执行时却没有收到预期的参数。具体表现为：

1. 代理正确识别了用户的姓名和邮箱信息
2. 代理触发了保存用户数据的动作
3. 但动作接收到的参数为空字典{}，而非预期的{'name':'test','email_address':'[e-mail]'}

根本原因分析

通过调试发现，问题出在Pydantic模型的版本兼容性上。Vocode核心库内部使用的是Pydantic v1版本，而开发者可能使用了Pydantic v2的语法定义动作输入模型。

关键发现点：

1. 在动作创建阶段，参数确实被正确解析为SaveUserDataActionInput实例
2. 但在转换为ActionInput时，参数被错误地转换为了空的BaseModel实例
3. 这种类型擦除现象是Pydantic版本不匹配的典型表现

解决方案

要解决此问题，必须确保使用与Vocode核心库兼容的Pydantic v1版本来定义所有动作相关的模型：

from pydantic.v1 import BaseModel, Field

class SaveUserDataActionInput(BaseModel):
    name: str = Field(..., description="验证过的用户名")
    email_address: str = Field(..., description="验证过的用户邮箱")

完整实现示例

以下是经过验证的正确实现方式：

from pydantic.v1 import BaseModel, Field
from typing import Dict, Any, Optional, Type
from vocode.streaming.action.base_action import BaseAction
from vocode.streaming.models.actions import (
    ActionInput,
    ActionOutput,
    VocodeActionConfig,
    FunctionCallActionTrigger,
)

class SaveUserDataActionInput(BaseModel):
    name: str = Field(..., description="验证过的用户名")
    email_address: str = Field(..., description="验证过的用户邮箱")

class SaveUserDataActionOutput(BaseModel):
    message: str

class SaveUserDataActionConfig(VocodeActionConfig, type="save_user_data"):
    action_trigger: FunctionCallActionTrigger = FunctionCallActionTrigger(
        type="action_trigger_function_call",
        function_name="save_user_data"
    )

class SaveUserDataAction(BaseAction[
    SaveUserDataActionConfig,
    SaveUserDataActionInput,
    SaveUserDataActionOutput
]):
    description = "保存用户联系信息到数据库"
    
    async def run(self, action_input: ActionInput[SaveUserDataActionInput]):
        # 现在可以正确访问action_input.params.name和action_input.params.email_address
        ...

最佳实践建议

1. 版本一致性：确保项目中所有Pydantic模型都使用v1版本
2. 类型注解：为动作类明确指定输入输出类型参数
3. 调试技巧：在动作的create_action_input方法中添加断点，验证参数转换过程
4. 错误处理：为动作添加参数验证逻辑，确保必要参数存在

总结

在Vocode核心库中实现自定义动作时，Pydantic版本兼容性是需要特别注意的关键点。通过使用正确的Pydantic v1版本定义模型，可以确保ChatGPT代理与自定义动作之间的参数传递正常工作。这一问题也提醒我们，在集成不同库时，版本依赖管理的重要性不容忽视。