1. 项目概述打造一个能与AI对话的Alexa技能如果你和我一样对智能语音助手和大型语言模型的结合充满兴趣那么你肯定想过能不能让家里的Alexa直接调用ChatGPT或者Claude来回答我的问题答案是肯定的而且实现起来比想象中要简单。今天要聊的这个项目alexa-skill-llm-intent就是一个开箱即用的Alexa技能模板它能让你快速搭建一个属于自己的、能与AI进行多轮对话的语音技能。简单来说这个项目提供了一个完整的脚手架。你只需要配置好一个兼容OpenAI API格式的LLM服务比如OpenAI官方、Anthropic的Claude或者OpenRouter这样的聚合平台然后通过几条命令就能把这个技能部署到你的Alexa开发者账户里。之后你就可以对着你的Echo设备说“Alexa问一下我的AI助手黑洞是如何形成的”然后听到Alexa用她标志性的声音为你朗读出由GPT-4或Gemini生成的答案。这个模板的核心价值在于它帮你处理了所有繁琐的“胶水”工作Alexa技能交互模型的搭建、意图Intent的处理、Lambda函数的编写、以及如何将用户的语音请求转换成LLM能理解的文本再把LLM的文本回复转换成Alexa的语音输出。你只需要关心最核心的部分接入哪个AI模型。这对于想快速验证想法、学习Alexa技能开发、或者单纯想打造一个私人AI语音助手的开发者来说是一个非常高效的起点。2. 核心架构与设计思路拆解2.1 为什么选择“单意图”设计打开项目的技能包文件skill-package/interactionModels/custom/en-US.json你会发现它的意图设计非常简洁。核心就是一个AskIntent。用户所有的问题无论是“解释一下量子计算”还是“今天的天气怎么样”都会先被路由到这个意图。这种设计思路与传统的、为每个具体功能如“问天气”、“设闹钟”定义独立意图的技能截然不同。背后的逻辑是这样的传统技能的交互模型是“确定性的”。开发者需要预先穷举用户可能说的所有话样本话语并将其映射到具体的意图和参数上。这对于功能固定的技能如查询航班、控制智能家居是有效的。但对于一个开放的、基于LLM的对话技能用户的问题千变万化无法预先定义。因此最合理的设计是采用“非确定性”的交互模型Alexa只负责识别用户“想要提问”这个意图并将用户说出的整个句子作为原始文本捕获下来然后全部交给后端的LLM去理解和处理。在AskIntent中通常会定义一个名为Question的槽位Slot其类型可能是AMAZON.SearchQuery。这个槽位类型是Alexa专门为捕获自由格式的搜索查询而设计的它能很好地抓取用户问题中的完整句子。这样一来技能的后端Lambda函数接收到的就是一个清晰的文本问题直接将其作为Prompt的一部分发送给LLM API即可。2.2 技能后端Lambda函数的工作流技能的后端逻辑集中在lambda/lambda_function.py文件中。这是一个标准的AWS Lambda函数作为Alexa技能服务ASK的请求处理器。其工作流可以分解为以下几个关键步骤请求路由Lambda函数接收来自Alexa服务的JSON请求。根据请求中的request[type]判断请求类型。对于LaunchRequest用户说“打开技能”函数会返回一个欢迎语并提示用户提问。对于IntentRequest则进一步判断是哪个意图。意图处理当识别到AskIntent时函数从请求的槽位中提取出用户的原始问题文本。构造LLM请求这是核心环节。函数会读取环境变量或配置文件config.json中预设的LLM API地址、密钥和模型名称。然后它构造一个符合OpenAI Chat Completion格式的请求体。这个请求体通常包含model: 指定的模型名称。messages: 一个消息数组至少包含一个system角色消息定义AI的行为如“你是一个有帮助的助手”和一个user角色消息即用户的问题。temperature,max_tokens等参数用于控制生成结果。调用LLM API使用Python的requests库或httpx库将构造好的请求发送到配置的LLM服务端点。处理响应并返回收到LLM的JSON响应后从中提取出choices[0].message.content即AI生成的文本回复。最后Lambda函数需要将这个文本回复包装成Alexa技能可以理解的响应格式主要是构造一个OutputSpeech对象。Alexa服务收到这个响应后就会将其转换为语音播报给用户。2.3 配置的灵活性与“Webhook”模式项目配置的亮点在于其灵活性。config.json文件不仅支持配置主流的LLM服务商还提供了一个非常巧妙的webhook模式。当你把llm_model设置为webhook时技能的行为会发生改变。此时llm_url不再被视为一个OpenAI兼容的API端点而是被视为一个普通的Webhook URL。Lambda函数会将整个Alexa请求上下文包括用户ID、问题文本、设备信息等打包成一个JSON负载并以POST请求的形式发送到你指定的llm_url。这个设计解决了什么问题自定义后端处理你可以在自己的服务器上运行任何复杂的逻辑。比如你可以先对用户问题进行分类再决定调用哪个AI模型或者将对话历史存入数据库实现真正的多轮对话记忆甚至可以将问题路由到你本地部署的大模型。协议转换如果你的AI服务提供商不使用OpenAI的API格式你可以在自己的Webhook服务里进行协议转换适配任何API。增加中间层你可以在Webhook服务中加入鉴权、限流、日志记录、内容过滤等中间件功能而不需要修改Lambda函数代码。这相当于把技能的后端逻辑从AWS Lambda中“解耦”出来给了开发者极大的自由度和控制权。对于企业级应用或需要复杂业务逻辑的场景这是一个非常实用的特性。3. 三种部署方式详解与实操要点项目提供了三种部署路径分别适合不同需求和熟练度的开发者。我将结合自己的踩坑经验详细说明每种方法的操作流程和注意事项。3.1 自动化部署推荐使用Makefile管理Alexa托管技能这是项目作者最推荐的方式也是体验最流畅的。它利用ASK CLI和一套Makefile脚本实现了技能的创建、配置、更新和调试的自动化。实操步骤与核心命令环境准备确保已安装Node.js和ASK CLI。安装ASK CLI的命令是npm install -g ask-cli。安装后运行ask configure登录你的亚马逊开发者账号。这个过程会打开浏览器进行OAuth授权请确保网络通畅。创建新技能在项目根目录下运行make new。这是一个交互式向导。关键选择当向导询问时必须依次选择Interaction Model交互模型Python编程语言Alexa-hosted skillsAlexa托管如果选择了其他选项如Node.js或AWS托管后续的Makefile脚本可能会因为目录结构或依赖不匹配而失败。配置技能创建成功后技能会出现在你的Alexa开发者控制台但其代码是空的“Hello World”模板。此时你需要编辑根目录下的config.json文件填入你的LLM API信息。更新技能运行make update skill你的技能slug。这个命令会做几件重要的事将本地的lambda/和skill-package/目录下的代码和模型文件同步到云端托管的Git仓库中。根据config.json中的invocation_name自动更新技能交互模型中的调用名称仅限en-US区域。触发云端构建部署Lambda函数并编译交互模型。重要提示这是一个单向同步。你在Alexa控制台网页上对代码或模型做的任何修改在下一次运行make update时都会被本地文件覆盖。所有开发都应在本地进行。我踩过的坑与心得技能创建卡住有时运行make new会卡在“Creating your Alexa hosted skill”这一步很久甚至超时。这通常是亚马逊后端服务临时性问题。我的经验是等待半小时到一小时后去Alexa控制台查看是否技能已创建。如果已创建但本地没有成功链接可以尝试用make init id技能ID命令重新导入该技能。区域限制Alexa托管技能在创建时需要选择区域如us-east-1 eu-west-1。如果你后续想使用make debug进行本地调试必须选择北美NA区域例如 us-east-1。因为ASK CLI的本地调试功能ask run目前仅支持NA区域的托管技能。如果选错了区域调试功能将无法使用。多技能管理make list命令可以列出本项目管理下的所有技能。每个技能在build/hosted/目录下都有一个对应的文件夹和一个_config.json文件。你可以为不同的技能比如一个用GPT-4一个用Claude配置不同的config.json文件并通过make config skillxxx fileyyy.json来分别指定实现多技能并行开发。3.2 手动部署通过Alexa开发者控制台上传这种方式不依赖命令行适合初学者或只想快速体验一下的用户。操作流程本地配置在项目根目录手动修改两个文件config.json: 填写你的LLM API信息。skill-package/interactionModels/custom/en-US.json: 找到invocationName字段将其值改为你想要的技能调用名例如my ai helper。生成部署包在终端运行make package。这会在build/package/目录下生成一个ZIP文件如skill.zip里面包含了技能包和Lambda代码。控制台操作登录 Alexa开发者控制台 点击“创建技能”。选择“自定义”模型选择“Python”作为后端选择“Alexa托管”作为资源。创建完成后进入技能的“代码”标签页。点击右上角的“导入代码”按钮选择刚才生成的ZIP文件。点击“保存”然后点击“构建模型”。注意事项这种方式虽然简单但失去了版本控制和自动化部署的优势。每次修改代码或模型后你都需要重新运行make package并手动上传ZIP包不利于迭代开发。它更适合一次性的部署或演示。3.3 高级部署使用ASK CLI创建自托管技能这种方式将技能的后端Lambda部署在你自己的AWS账户中而不是Alexa托管环境。这提供了最大的灵活性例如可以使用更高的内存、更长的超时时间、关联其他AWS服务但复杂度也最高。步骤简述在一个新的目录不要是项目根目录下运行ask new --template-url https://github.com/paulotruta/alexa-skill-llm-intent.git。跟随向导这次在“选择托管方式”时选择“AWS Lambda”自托管。向导会引导你配置AWS凭证和技能信息最终会在当前目录生成一个完整的技能项目文件夹。进入该文件夹配置config.json和交互模型文件。运行ask deploy进行部署。这个命令会通过CloudFormation在你的AWS账户中创建Lambda函数、IAM角色等资源并将技能注册到你的开发者账户。适用场景与风险适用需要连接自有数据库、使用特定AWS服务如DynamoDB存储对话历史、或对Lambda运行环境有特殊要求的进阶项目。风险你需要自行管理AWS资源会产生Lambda运行费用虽然通常很低。部署流程更复杂出错排查的链路也更长。对于刚接触Alexa开发和AWS的开发者不建议首选此方案。4. 核心代码解析与定制化开发4.1 Lambda函数核心逻辑剖析让我们深入lambda/lambda_function.py看看它是如何工作的。核心函数是lambda_handler(event, context)它是所有Alexa请求的入口。def lambda_handler(event, context): 主Lambda处理函数。 # 1. 验证请求来自Alexa if (event[session][application][applicationId] ! os.environ[SKILL_ID]): raise ValueError(Invalid Application ID) # 2. 根据会话是否新会话初始化或获取对话历史 if event[session][new]: on_session_started({requestId: event[request][requestId]}, event[session]) session_attributes {} else: session_attributes event[session].get(attributes, {}) # 3. 路由请求 if event[request][type] LaunchRequest: return on_launch(event[request], session_attributes) elif event[request][type] IntentRequest: return on_intent(event[request], session_attributes) elif event[request][type] SessionEndedRequest: return on_session_ended(event[request], session_attributes)关键点解析应用ID验证这是一个重要的安全措施确保请求只来自你授权的技能。SKILL_ID应从环境变量读取在Alexa托管环境中会自动注入。会话管理session_attributes是实现在同一会话中保持上下文多轮对话的关键。你可以在这里存储之前的问答历史。模板中可能没有实现完整的多轮对话逻辑但这为你提供了扩展的基础。请求路由清晰地将Launch、Intent、SessionEnded三种请求类型分发给不同的处理函数。on_intent函数是处理用户提问的核心def on_intent(intent_request, session_attributes): 处理所有意图请求。 intent_name intent_request[intent][name] # 分发到具体的意图处理器 if intent_name AskIntent: return handle_ask_intent(intent_request, session_attributes) elif intent_name in [AMAZON.CancelIntent, AMAZON.StopIntent]: return handle_session_end_request() else: raise ValueError(fInvalid intent: {intent_name})handle_ask_intent函数会提取用户问题调用get_llm_response函数与AI交互最后封装响应。4.2 如何实现多轮对话记忆模板默认可能是单轮问答。要实现多轮对话让AI记住之前的聊天内容你需要修改会话属性的使用方式。核心思路是将之前的对话历史包括用户的问题和AI的回答以列表的形式存储在session_attributes中并在每次请求时将其作为上下文传递给LLM。修改示例在handle_ask_intent中获取历史记录# 从会话属性中获取对话历史如果没有则初始化 conversation_history session_attributes.get(conversation_history, [])构造包含历史的Prompt将conversation_history列表中的每条记录应包含role和content添加到发送给LLM的messages列表中放在当前用户问题之前。将本次问答加入历史并保存# 将用户问题加入历史 conversation_history.append({role: user, content: user_question}) # 将AI回答加入历史 conversation_history.append({role: assistant, content: ai_response_text}) # 为防止上下文过长可以只保留最近N轮对话 if len(conversation_history) 10: # 保留最近5轮对话10条消息 conversation_history conversation_history[-10:] # 保存回会话属性 session_attributes[conversation_history] conversation_history在返回的响应中携带更新后的会话属性确保build_response函数将session_attributes包含在响应中这样下次请求时才能拿到更新后的历史。注意Alexa的会话属性在会话结束后会销毁。要实现跨会话的记忆你需要将历史存储到外部数据库如DynamoDB使用用户的userId作为主键。这超出了基础模板的范围但却是生产级应用必须考虑的。4.3 定制系统提示词与AI行为系统提示词System Prompt是塑造AI在对话中角色和行为的关键。在模板中它可能被定义在get_llm_response函数内部或作为一个配置项。你可以在config.json中增加一个字段例如llm_system_prompt然后在代码中读取它{ invocation_name: 我的AI学者, llm_url: https://api.openai.com/v1/chat/completions, llm_model: gpt-4, llm_key: sk-..., llm_system_prompt: 你是一位知识渊博且风趣幽默的大学教授擅长用生动的比喻和简单的例子解释复杂的科学概念。回答要简洁控制在3句话以内。 }在代码中system_prompt config.get(llm_system_prompt) or 你是一个有帮助的助手。 messages [{role: system, content: system_prompt}]通过定制系统提示词你可以让技能变身为专业顾问、讲故事伙伴、语言学习陪练等等极大地丰富了技能的可能性。5. 测试、调试与问题排查实录5.1 在开发者控制台进行功能测试部署技能后第一件事就是在Alexa开发者控制台进行测试。进入你的技能页面点击“测试”标签页。将测试模式从“禁用”改为“开发”。在左侧的输入框中你可以直接输入文本指令来模拟语音例如“问我的AI助手珠穆朗玛峰有多高”。右侧会显示JSON格式的请求和响应以及模拟的语音输出。这是最重要的调试信息源。如何分析测试结果查看请求Request确认request.intent.name是否正确识别为AskIntent并检查slots.Question.value是否完整、准确地捕获了你的问题文本。如果这里出错问题出在交互模型样本话语不足或槽位类型不对。查看响应Response检查response.outputSpeech.ssml或response.outputSpeech.text的内容。如果这里为空或包含错误信息问题出在Lambda函数逻辑或LLM API调用上。查看日志如果Lambda函数中使用了print或logger语句其输出会显示在“日志”标签页中。这是排查代码逻辑和API调用问题的关键。5.2 使用Makefile进行本地调试限NA区域对于使用“自动化部署”方式且技能位于北美区域的开发者可以使用make debug skill技能slug命令进行更强大的本地调试。这个命令实际上在后台运行了ask run。它会在你的本地机器上启动一个代理服务器。将云端技能的Lambda端点临时重定向到你的本地机器。当你通过控制台或真实设备测试技能时请求会被路由到本地运行的lambda_function.py。实操步骤确保在config.json中使用了测试用的API Key或本地LLM服务地址如本地部署的Ollama。在项目根目录运行make debug skill你的技能。终端会显示一个URL例如Webserver started: https://localhost:3000。此时去Alexa控制台测试技能你会发现请求被本地代码处理终端会打印出详细的请求和响应日志你可以实时修改代码并看到效果无需重复部署。重要限制如前所述此功能仅适用于托管在北美区域如us-east-1的技能。如果你的技能托管在欧盟eu-west-1此命令将无法工作。5.3 常见问题与解决方案速查表以下是我在开发和测试过程中遇到的一些典型问题及解决方法问题现象可能原因排查步骤与解决方案技能回应“技能没有响应”或直接报错。1. Lambda函数代码有语法错误或运行时异常。2. LLM API调用失败网络、密钥错误、额度不足。3. 响应格式不符合Alexa要求。1.查看CloudWatch日志在AWS控制台找到对应技能的Lambda函数查看其日志。这是定位运行时错误的最直接方法。2.简化测试在Lambda函数中先注释掉LLM调用直接返回一个固定的文本响应如“测试成功”。如果此时技能正常问题就出在LLM API环节。3.检查API密钥和端点确认config.json中的信息正确无误特别是密钥是否有空格或换行符。Alexa能识别意图但说“我没有听清你的问题”。AskIntent中的Question槽位未能正确捕获用户输入。1.检查交互模型确认Question槽位的类型是AMAZON.SearchQuery。2.增加样本话语在en-US.json文件中为AskIntent添加更多、更多样化的样本话语Utterances覆盖不同的提问方式。技能调用名称不生效Alexa说“找不到名为xxx的技能”。1. 调用名称包含Alexa的保留词或不符合命名规范。2. 模型构建失败或未部署。3. 技能未发布仅限测试模式而测试设备未与开发者账号绑定。1.检查调用名称不能使用“Alexa”、“Amazon”、“Echo”等词。最好是两个或三个单词的组合如“AI助手”、“我的机器人”。2.在控制台“构建”模型确保每次修改交互模型后都点击了“保存”和“构建模型”并等待构建完成。3.绑定测试设备在开发者控制台“测试”页面的“设备”下拉框中选择“你的设备”并按照提示登录绑定。LLM回复内容过长Alexa播报被截断或超时。Alexa语音响应有长度限制约8000个字符Lambda函数执行时间也有超时限制Alexa托管默认8秒。1.在代码中截断回复在发送文本给Alexa前检查长度如果超过一定字符如6000则截断并添加提示语如“回答过长已为您截断...”。2.优化LLM参数在调用LLM API时设置max_tokens参数限制生成文本的最大长度。3.处理超时Lambda函数中设置合理的超时时间并在接近超时时返回一个友好的提示如“思考时间有点长请再问我一个简单点的问题吧”。使用Webhook模式时收不到请求或请求格式不对。1. Webhook URL不可达防火墙、网络问题。2. Webhook服务未正确处理POST请求或返回的格式不对。1.使用公网可访问的URL确保你的Webhook服务有公网IP或域名并且端口如443是开放的。可以使用ngrok或localtunnel为本地开发服务生成临时公网地址。2.检查请求负载在Webhook服务中打印接收到的整个请求体request.body确认Alexa发送的数据结构。确保你的服务返回的JSON格式符合Alexa技能响应格式。5.4 性能优化与成本控制心得选择轻量模型对于语音交互回复通常不需要特别长或复杂。可以考虑使用更便宜、更快的模型如gpt-3.5-turbo、claude-3-haiku或gemini-1.5-flash。在config.json中切换模型非常方便。设置合理的超时和令牌限制在Lambda函数中为requests.post调用设置超时如5秒。在调用LLM API时明确设置max_tokens如500这既能控制响应长度也能避免因生成过长文本而产生意外费用。利用OpenRouter等聚合平台OpenRouter提供了统一接口访问多个模型并且有按Token计费的清晰价格和免费额度非常适合开发和测试。启用Lambda Provisioned Concurrency仅自托管如果你使用自托管Lambda并面临冷启动问题第一次调用响应慢可以考虑配置预置并发但这会增加成本。这个项目作为一个强大的起点已经解决了从想法到可运行技能之间的大部分工程问题。剩下的就是发挥你的想象力去定制AI的角色、优化对话体验、甚至集成更多外部服务打造出独一无二的语音AI助手。