鸿蒙智能体开发实战：22.真机测试

前言开发完成智能体应用后需要进行充分的测试确保其正常工作。本文介绍如何在本地和真实设备上进行测试以及部署到生产环境的完整流程。本地测试启动开发服务器# 激活虚拟环境sourcevenv/bin/activate# 启动服务python main.py# 或使用 uvicornuvicorn main:app--host0.0.0.0--port8080--reload使用 curl 测试测试健康检查curlhttp://localhost:8080/health预期响应{status:ok,message:Service is healthy}测试 Initialize 方法curl-XPOST http://localhost:8080/agent/message\-HContent-Type: application/json\-d{ jsonrpc: 2.0, id: 1, method: initialize }预期响应{jsonrpc:2.0,id:1,result:{agentSessionId:8f01f3d172cd4396a0e535ae8aec6687,agentSessionTtl:604800}}测试 Message/Stream 方法curl-XPOST http://localhost:8080/agent/message\-HContent-Type: application/json\-Hagent-session-id: 8f01f3d172cd4396a0e535ae8aec6687\-d{ jsonrpc: 2.0, id: 2, method: message/stream, params: { id: task-001, sessionId: session-001, message: { role: user, parts: [{ kind: text, text: 你好 }] } } }使用 Python 脚本测试# tests/test_agent.pyimporthttpximportjson BASE_URLhttp://localhost:8080deftest_initialize():测试初始化接口responsehttpx.post(f{BASE_URL}/agent/message,json{jsonrpc:2.0,id:1,method:initialize})dataresponse.json()print(Initialize 响应:,json.dumps(data,indent2,ensure_asciiFalse))assertagentSessionIdindata.get(result,{})returndata[result][agentSessionId]deftest_message_stream(session_id):测试流式消息接口withhttpx.stream(POST,f{BASE_URL}/agent/message,headers{Content-Type:application/json,agent-session-id:session_id},json{jsonrpc:2.0,id:2,method:message/stream,params:{id:task-001,sessionId:session-001,message:{role:user,parts:[{kind:text,text:你好请介绍一下你自己}]}}},timeout60.0)asresponse:print(Stream 响应:)forlineinresponse.iter_lines():ifline.startswith(data:):datajson.loads(line[5:])print(json.dumps(data,indent2,ensure_asciiFalse))if__name____main__:session_idtest_initialize()print(f获取 session_id:{session_id})test_message_stream(session_id)使用 Postman 测试创建新请求设置方法为 POSTURL:http://localhost:8080/agent/messageHeaders:Content-Type: application/jsonagent-session-id: your-session-idBody (raw JSON):{jsonrpc:2.0,id:2,method:message/stream,params:{id:task-001,sessionId:session-001,message:{role:user,parts:[{kind:text,text:你好}]}}}小艺开放平台真机测试上述测试方式是在开发者本地对A2A服务进行功能验证。在完成智能体编排后还可以通过小艺开放平台的真机测试功能在真实的鸿蒙设备上体验智能体的完整效果。真机测试概述真机测试为开发者提供了在智能体上架前即可在端侧设备上体验智能体使用效果的能力。这意味着你无需发布正式版本即可在手机等真实设备上测试智能体的对话效果和能力。图1调试与预览区域中的真机测试入口真机测试使用流程第一步配置真机测试白名单在智能体的调试与预览区域点击真机测试图标选择【白名单】跳转至智能体白名单配置页面。创建真机测试用户组配置项说明创建入口智能体测试白名单页面 或 小艺开放平台 → 通用设置 → 真机测试管理用户组上限每个团队最多100个用户组用户上限每个用户组最多100个用户添加方式支持单用户添加【添加用户】和【批量导入】账户类型手机号码或邮箱需已注册华为账号重要限制添加的测试账号必须为当前团队账号下的成员且拥有小艺开放平台的权限否则会提示仅可添加本团队账号下的成员。Inhouse类型的账号暂时无法为团队成员添加小艺开放平台的权限如需要进行真机测试请使用主账号进行测试。第二步发布真机测试在调试与预览区域点击【真机测试】→【发布真机测试】提示请求成功后白名单内人员通过重新启动小艺等待3至5分钟在对话列表中即可看到带有开发中标签的智能体第三步在设备上测试在华为手机上打开小艺即可在对话列表中看到开发中标签的智能体。你可以像普通用户一样与智能体对话测试其在真实环境下的表现。真机测试有效期管理项目说明有效期发布后15天内有效范围基准以最后一次发布所选用户组为准取消测试编排页面 → 【真机测试】→ 【取消发布】图2真机测试发布界面显示有效期和取消发布选项真机测试用户组创建入口1在智能体的测试白名单页面进行配置入口2通过小艺开放平台 → 通用设置 → 真机测试管理以智能体测试白名单页面为例图3在测试白名单页面创建用户组并添加测试用户# 真机测试用户组创建步骤1. 在测试白名单页面点击右上角【新建用户组】2. 填写用户组名称3. 点击操作栏内【管理用户】管理组成员4. 选择【添加用户】或【批量导入】5. 输入用户手机号或邮箱需已注册华为账号6. 确认添加规则限制每个团队最多可创建100个用户组每个用户组最多可添加100个用户添加用户时根据注册账户类型填写需拥有小艺开放平台权限的团队成员调试台使用指南在实际使用智能体时如果响应不符合预期、速度过慢甚至不响应可以通过调试台查看智能体的执行细节快速排查问题。调试台概述小艺开放平台的调试台功能提供全链路调试能力你可以在调试台查看每一条用户请求从输入到响应的全流程包括模型调用、工作流执行、知识库检索等详细信息。适用场景场景说明开发调试搭建智能体时输出不符合预期需修改流程线上排障用户反馈智能体不响应、返回错误信息时诊断定位进入调试台通过智能体的编排页面进入调试台# 调试台操作步骤1. 在智能体编排页面右侧的调试与预览区域2. 发送一条消息开始与智能体对话3. 收到智能体响应后4. 点击右上角的调试选项进入调试台页面进入调试台页面后默认展示当前消息的响应过程你可以筛选或选择查看之前某次对话的响应过程。调试台信息说明调试台中展示每轮对话运行的全链路包括调用流程请求从进入系统到返回响应的完整路径节点详情每个节点的状态、耗时等详细信息输入输出各节点的输入数据和输出数据Token消耗各环节的token使用情况基础信息页面默认展示当前会话的信息你也可以通过会话时间来筛选会话例如查看某一天所有运行的会话。会话概览数据包含指标说明会话整体耗时从请求到响应的总用时Token消耗本次会话消耗的总token数节点数量本次请求涉及的处理节点数状态成功/失败/超时调测树在排查和定位问题时往往需要查看请求的完整调用链路。平台采用可视化树形图展示请求响应的完整链路及各节点的执行情况。查看请求响应链路你可以通过树形图查看本次请求的完整响应流程。每个节点代表一个处理步骤例如用户输入 └─ 意图识别 └─ 知识库检索 └─ 大模型生成 └─ 结果输出查看节点详细信息点击任一节点可查看该节点的详细信息包括{node_id:node_llm_001,node_type:大模型节点,duration:1520,status:success,token_usage:{prompt_tokens:1200,completion_tokens:350,total_tokens:1550},input:{model:deepseek-r1,messages:[...]},output:{content:根据知识库的信息产品的保修期为...}}火焰图除了调测树调试台还提供火焰图来直观查看各个流程的耗时分布。火焰图示例 [意图识别] ████ 200ms [知识库检索] ████████████ 600ms [大模型生成] ██████████████████████ 1200ms [后处理] ███ 150ms横轴表示耗时各流程按照执行顺序排列点击进度条可查看节点的具体调用情况颜色越深、条形越长表示耗时越多指定对话调试支持在调试与预览页面打开指定的对话调试详情信息点击回复内容下方的调试图标即可查看右侧本地调试的内容详情。调试常见问题Q: 调试与预览窗口中的运行结果与调试台的运行结果有何区别A: 调试与预览窗口中的运行结果会实时展示请求的响应过程当运行完毕后会展示最终的信息。而调试台中会展示指定请求的完整响应节点和每个节点的执行信息。Q: 网页调试时如何获取本次对话用于问题定位的sessionIdA:打开浏览器调试台活动栏中选择网络Network调测智能体点击名称为run的请求选择消息或Payload取出第一条数据中的sessionId、interactionId若有多条run运行记录可以根据运行时间判断Docker 部署测试构建 Docker 镜像# Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8080 CMD [python, main.py]Docker Compose 配置# docker-compose.ymlversion:3.8services:agent:build:.ports:-8080:8080environment:-VOLCANIC_API_KEY${VOLCANIC_API_KEY}-VOLCANIC_BASE_URL${VOLCANIC_BASE_URL}-LANGUAGE_MODEL${LANGUAGE_MODEL}restart:unless-stoppedhealthcheck:test:[CMD,curl,-f,http://localhost:8080/health]interval:30stimeout:10sretries:3启动 Docker 容器# 配置环境变量cp.env.example .envvim.env# 启动容器docker-composeup-d# 查看状态docker-composeps# 查看日志docker-composelogs-f# 停止容器docker-composedown生产环境部署服务器要求Python 3.9至少 2GB 内存稳定的网络连接访问大模型 API一键部署脚本#!/bin/bash# deploy.shset-eAPP_NAMEai-assistantAPP_DIR/opt/$APP_NAMESERVICE_NAME$APP_NAME.serviceecho 开始部署$APP_NAME# 创建应用目录sudomkdir-p$APP_DIRsudochown$USER:$USER$APP_DIR# 复制文件cp-r.$APP_DIR/cd$APP_DIR# 安装依赖pip3install-rrequirements.txt# 创建 systemd 服务文件sudotee/etc/systemd/system/$SERVICE_NAME/dev/nullEOF [Unit] Description$APP_NAMEService Afternetwork.target [Service] Typesimple User$USERWorkingDirectory$APP_DIREnvironmentPATH$APP_DIR/venv/bin ExecStart$APP_DIR/venv/bin/python main.py Restartalways RestartSec10 [Install] WantedBymulti-user.target EOF# 重载 systemdsudosystemctl daemon-reload# 启动服务sudosystemctlenable$SERVICE_NAMEsudosystemctl start$SERVICE_NAMEecho 部署完成 echo查看状态sudo systemctl status$SERVICE_NAMEecho查看日志sudo journalctl -u$SERVICE_NAME-f使用脚本部署# 安装sudo./deploy.shinstall# 配置 API 密钥sudovim/opt/ai-assistant/.env# 启动服务sudo./deploy.sh start# 查看状态sudo./deploy.sh status# 查看日志sudo./deploy.sh logs# 停止服务sudo./deploy.sh stopNginx 反向代理配置# /etc/nginx/sites-available/ai-assistant server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # SSE 支持 proxy_set_header Connection ; proxy_http_version 1.1; proxy_set_header X-Accel-Buffering no; proxy_buffering off; proxy_cache off; # 超时设置 proxy_connect_timeout 60s; proxy_send_timeout 300s; proxy_read_timeout 300s; } }启用配置sudoln-s/etc/nginx/sites-available/ai-assistant /etc/nginx/sites-enabled/sudonginx-tsudosystemctl reload nginx日志管理日志文件位置logs/ ├── ai-assistant-YYYYMMDD.log # 主日志 ├── request-YYYYMMDD.log # 请求日志 ├── sse-YYYYMMDD.log # SSE 流式输出日志 └── volcanic-YYYYMMDD.log # API 调用日志日志查看脚本#!/bin/bash# logs.shLOG_DIRlogsTODAY$(date%Y%m%d)case$1inmain)tail-n${2:-100}$LOG_DIR/ai-assistant-$TODAY.log;;request)tail-n${2:-100}$LOG_DIR/request-$TODAY.log;;sse)tail-n${2:-100}$LOG_DIR/sse-$TODAY.log;;follow)tail-f$LOG_DIR/ai-assistant-$TODAY.log;;errors)grep-ierror\|exception\|failed$LOG_DIR/*.log|tail-100;;*)echoUsage:$0{main|request|sse|follow|errors};;esac常见问题排查1. 服务无法启动# 检查端口占用lsof-i:8080# 检查 Python 依赖pip list|grepfastapi# 查看详细错误python main.py212. API 调用失败# 检查环境变量echo$VOLCANIC_API_KEY# 测试 API 连通性curl-HAuthorization: Bearer$VOLCANIC_API_KEY\https://api.example.com/v1/models3. SSE 连接中断检查 Nginx 缓冲配置增加超时时间检查防火墙设置性能监控健康检查端点# 定期检查curlhttp://localhost:8080/health# 添加到监控系统*/5 * * * *curl-fhttp://localhost:8080/health||echoService down请求统计# 在应用中添加简单的统计request_count0error_count0app.get(/stats)asyncdefget_stats():return{request_count:request_count,error_count:error_count}测试方法对比总结测试方法测试范围适用阶段优点局限curl/脚本A2A API功能开发初期快速验证自动化无法测试端侧效果PostmanA2A API功能开发中期可视化方便调试原生接口不够用真机测试端到端用户体验发布前真实设备完整流程需要设备用户组配置调试台全链路执行详情开发排障可视化调测树火焰图无法替代功能测试小结本文全面介绍了鸿蒙智能体开发中的测试与调试方法本地API测试curl、Python脚本、Postman对A2A服务进行功能性验证真机测试通过小艺开放平台在真实设备上体验智能体调试台全链路可视化调测树形图和火焰图双重诊断Docker部署测试容器化部署和编排验证生产部署systemd服务管理、Nginx反向代理配置日志管理日志文件分类和查看脚本问题排查常见错误的定位和解决方案掌握这些测试和调试工具能够显著提升智能体开发效率确保上架质量。从API功能验证到端侧用户体验再到生产环境的稳定运行每个环节都不容忽视。如果觉得本文对你有帮助欢迎点赞 、收藏 ⭐ 和关注 你的支持是我持续创作的动力相关资源小艺开放平台 - 真机测试管理智能体调试 - 官方文档华为开发者联盟 - 文档中心小艺开放平台 - 开发者控制台管理团队账号 - 开发者联盟Inhouse类型账号说明A2A协议技术规范 - 官方文档Nginx官方文档Docker官方文档Python httpx官方文档