适用于产品: 幻尔科技 Jetson 系列与树莓派系列（ROSOrin Pro智能小车 / JetRover三合一智能车 / JetAuto麦轮机器人 / LanderPi三合一ROS2智能车 / ArmPi Ultra智能机械臂 / TurboPi智能视觉小车 / TonyPi智能视觉人形机器人 等）
涉及模块: AI大模型 / large_models / config.py / 手机 App 大模型功能
核心标签: 通用 #大模型 #APIKey #config.py #视觉大模型
Key、接口地址、模型名必须来自同一个平台的同一个账号，三项要一起改。只改其中一项（最常见的是只换 Key、或只换模型名）是"明明配置了却不生效"的头号原因。
一、配置文件在哪里
以各机型出厂镜像为例，config.py 的位置如下：
| 产品（举例） | config.py 路径 |
|---|---|
| ROSOrin Pro智能小车 / JetRover三合一智能车 / JetAuto麦轮机器人 | ~/ros2_ws/src/large_models/large_models/large_models/config.py |
| LanderPi三合一ROS2智能车 | ~/ros2_ws/src/large_models/large_models/large_models/config.py |
| ArmPi Ultra智能机械臂 | ~/ros2_ws/src/large_models/large_models/config.py |
| TonyPi智能视觉人形机器人（无 ROS） | /home/pi/large_models/config.py 与 /home/pi/embodied_intelligence/common/config.py |
（1）以 ROSOrin Pro智能小车 为例，官方教程给的进入与打开方式：
cd ~/ros2_ws/src/large_models/large_models/large_models/
gedit config.py
（2）修改后按 Ctrl+S 保存并关闭编辑器，再重新启动玩法或服务，配置才会生效。
二、Key 填到哪个变量
（1）阿里云百炼（国内，文本大模型与语音识别、语音合成）：按官方课程《11.4大模型综合应用》第 12.4.2 节完成实名认证、开通服务、创建 API-Key，然后填到 config.py 的 aliyun_api_key。
（2）阶跃星辰（国内，视觉大模型）：同课程第 12.4.3 节。拿到 Key 后填到 stepfun_api_key，接口地址保持 stepfun_base_url 不变。
（3）国外平台：OpenAI 填 llm_api_key / llm_base_url；OpenRouter 填 vllm_api_key / vllm_base_url。部分机型的国内视觉玩法也走 vllm_ 这三个变量，改之前先确认当前生效的是哪一组。
（4）不联网的离线方案：使用机器人本机的 Ollama 服务（课程《12.5离线大模型应用》），配置里的 ollama_host 指向本机服务。
变量组对照：
| 变量组 | 用途 | 默认接口地址 |
|---|---|---|
| aliyun_api_key / aliyun_base_url / aliyun_llm_model | 国内文本大模型 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| aliyun_vllm_model | 国内视觉大模型 | 同上 |
| aliyun_asr_model / aliyun_tts_model | 语音识别 / 语音合成 | 同上 |
| stepfun_api_key / stepfun_base_url / stepfun_vllm_model | 国内视觉大模型（部分玩法走这组） | https://api.stepfun.com/v1 |
| llm_api_key / llm_base_url / llm_model | 国外文本大模型 | https://api.openai.com/v1 |
| openai_vllm_model | 国外视觉大模型 | 同上 |
| vllm_api_key / vllm_base_url / vllm_model | 国外或第三方聚合平台的视觉大模型 | https://openrouter.ai/api/v1 |
| ollama_host | 离线本机大模型 | http://localhost:11434 |
（5）决定"哪一组生效"的是环境变量 ASR_LANGUAGE：值为 Chinese 时读取阿里云那一组，否则读取 OpenAI 那一组。改了 aliyun_ 却没反应，先确认它是不是 Chinese。
三、模型名怎么填
（1）平台上的模型会不断更新，不要照抄别人截图里的名字。先用一条命令把当前账号可用的模型列表拉下来，从列表里挑名字填进对应变量：
python3 -c "from openai import OpenAI; c = OpenAI(api_key='{你的Key}', base_url='{接口地址}'); print([m.id for m in c.models.list()])"
（2）{接口地址} 填你要使用那一组的 base_url，阿里云为 https://dashscope.aliyuncs.com/compatible-mode/v1，阶跃星辰为 https://api.stepfun.com/v1。返回 200 说明 Key 有效，返回内容就是账号当前可用的模型清单。
（3）换平台时，地址、模型名、Key 要一起换；同一组里文本模型和视觉模型分别填在 llm 与 vllm 对应的变量上。
（4）名字里带 image、wan、z-image 的图像生成类模型，不能填进视觉大模型变量。
四、报错对照表
| 报错关键字 | 含义 | 处理方式 |
|---|---|---|
| invalid_api_key / 401 | Key 本身错误、为空，或复制时带了空格换行 | 重新复制 Key，注意首尾不要有多余字符 |
| access_denied / 403 | Key 有效，但该账号没有这个模型的权限 | 到平台开通该模型，或换列表里有权限的模型名 |
| model_not_found / model_invalid / Unsupported model / 404 | 模型名不存在、已下线，或该模型不支持 OpenAI 兼容模式调用 | 用第三节的命令重新拉一次列表，换可用模型名 |
| messages.0.role must be user / invalid_parameter_error | 请求体被服务端严格校验拒绝，常见原因是模型名填成了图像生成类 | 换掉模型名 |
| Arrearage / account is in good standing | 平台账号欠费或免费额度用尽 | 充值或更换可用 Key，此前的测试结论都要重做 |
| 节点 process has died / exit code 1 | 上一层调用抛异常后节点退出 | 向上翻日志找最后一层异常的关键字，再对照本表 |
报错先认最后一层异常的模块名：串口字样多半是语音硬件那一路，openai 字样才是大模型接口，能省一半排查时间。
五、延伸参考
- 阿里云百炼控制台、阶跃星辰开放平台（申请 Key、开通模型、查看余额与用量）
- 官方课程：AI大语言模型课程《11.4大模型综合应用》（12.4.2 阿里云、12.4.3 阶跃星辰）、《11.2_多模态大模型应用》、《12.5离线大模型应用》
六、资源下载
若你的资料包丢失或找不到上述配置文件，可通过以下途径获取：
- 官方在线课程与资料库：幻尔科技官网在线教程
- 联系购买设备的店铺客服（淘宝 / 京东 / 官网客服）
- 人工技术支持：提供订单号即可免费领取最新版本的固件与源码包