LLM-PID-Tuner配置详解:config.json 12个关键字段一次填对
LLM-PID-Tuner配置详解:config.json 12个关键字段一次填对
LLM-PID-Tuner 是一款基于 LLM 的极简 PID 自动调参系统(CLI 版),config.json 是它的"总开关":填对了配置,硬件、仿真、Simulink 三种模式才能顺利跑通。本文带你逐个吃透 12 个关键字段,一次填对不再踩坑。
第 1 步:先拿到默认 config.json
第一次运行 tuner.py、simulator.py 或打包版 llm-pid-tuner.exe 时,如果当前目录没有 config.json,程序会自动生成一份默认配置。如果想先对照模板,也可以直接参考仓库里的 config.example.json。
配置加载逻辑位于 core/config.py,加载顺序为:
- 默认值(内置在
DEFAULT_CONFIG中) config.json(覆盖默认值)- 环境变量(优先级最高,同名变量会覆盖配置文件)
💡 新手优先用
config.json,直观好改;写自动化脚本时再用环境变量。
硬件串口 3 字段:真实设备调参必填
| 字段 | 默认值 | 怎么填 |
|---|---|---|
SERIAL_PORT |
AUTO |
不确定就先填 AUTO,程序会扫描串口让你选;知道端口号(如 COM5)可直接写死 |
BAUD_RATE |
115200 |
必须和单片机固件保持一致,对不上就是"连上了但没数据" |
HARDWARE_PROFILE |
generic_serial_csv |
普通 CSV 固件保持默认;特定板卡(如 stm32f407_openmv、mspm0_datavision)才需要改 |
默认串口协议是 MCU 持续上报一行 CSV:
timestamp_ms,setpoint,input,pwm,error,p,i,d
没有现成固件的同学,建议直接用仓库里的 firmware.cpp 对齐协议,别自己临时改格式。
LLM 4 字段:所有模式的核心,不填无法调参
这组字段决定"谁来帮你调参",是整份配置里最重要的部分:
LLM_API_KEY:你的 API Key,必须替换掉占位符your-api-key-hereLLM_API_BASE_URL:接口地址,OpenAI 官方填https://api.openai.com/v1;兼容接口填对应服务商的/v1地址LLM_MODEL_NAME:模型名,如gpt-4oLLM_PROVIDER:协议类型,openai/openai_claude/anthropic三选一
常见组合速查(详细解析逻辑见 llm/client.py):
| 使用方案 | LLM_API_BASE_URL 示例 |
LLM_PROVIDER |
|---|---|---|
| OpenAI 官方 | https://api.openai.com/v1 |
openai |
| DeepSeek / MiniMax 兼容接口 | 服务商的 /v1 地址 |
openai |
| Claude 中转站 / OneAPI | 中转站的 /v1 地址 |
openai_claude |
| Anthropic 原生接口 | https://api.anthropic.com |
anthropic |
| Ollama 本地部署 | http://localhost:11434/v1 |
openai |
⚠️ 最常见的报错场景:用 OpenAI 兼容接口却把 LLM_PROVIDER 填成 anthropic,或者把 Claude 中转站当成了 Anthropic 原生接口。
调参行为 5 字段:控制"调多狠、调多久、何时停"
新手建议先保持默认,采样不够或网络慢时再动:
BUFFER_SIZE(默认100):每轮评测累积的采样点数量。数据攒够才做一轮分析和 LLM 请求,采样太少可加大MIN_ERROR_THRESHOLD(默认0.3):平均误差低于该值且状态稳定时,可直接判定"低误差收敛"提前结束MAX_TUNING_ROUNDS(默认50):最大调参轮数,防止无限跑下去GOOD_ENOUGH_AVG_ERROR(默认0.1):"已经够好"的误差阈值,与GOOD_ENOUGH_STEADY_STATE_ERROR、GOOD_ENOUGH_OVERSHOOT一起触发提前停止,避免过调(判断逻辑在 pid_safety.py)PID_LIMITS:P/I/D 的护栏,配置绝对上下限和单轮最大增幅。程序会把实际限幅写进 LLM 提示词,并在下发前强制执行,防止参数越调越离谱。按场景分为default/python_sim/simulink三套
另外,REQUIRED_STABLE_ROUNDS(默认 3 轮)配合"够好"判定:达标后保持当前参数观察,连续稳定才停止;中途变差会清零计数,恢复正常调参。
按场景抄作业:3 份最小配置
真实硬件模式(改 7 项即可):
{
"SERIAL_PORT": "AUTO",
"BAUD_RATE": 115200,
"HARDWARE_PROFILE": "generic_serial_csv",
"LLM_API_KEY": "sk-your-key",
"LLM_API_BASE_URL": "https://api.openai.com/v1",
"LLM_MODEL_NAME": "gpt-4o",
"LLM_PROVIDER": "openai"
}
本地 Python 仿真(只需 LLM 4 项,去掉串口 3 项即可跑 python simulator.py)。
Simulink 模式在 LLM 4 项基础上再补 6 项:MATLAB_MODEL_PATH、MATLAB_PID_BLOCK_PATH、MATLAB_ROOT、MATLAB_OUTPUT_SIGNAL、MATLAB_SIM_STEP_TIME、MATLAB_SETPOINT。完整步骤见 docs/zh-CN/MATLAB_GUIDE.md。
可选字段速查:代理、CSV 导出
| 字段 | 说明 |
|---|---|
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY |
需要代理才填,留空即不启用;配置会自动同步到环境变量 |
CSV_EXPORT_PATH |
填路径(如 logs/tuning_data.csv)即可把每轮数据追加导出,自动记录 session_id 和轮次,方便 Excel / MATLAB 分析;留空不导出,字段定义见 core/csv_export.py |
LLM_REQUEST_TIMEOUT |
LLM 请求超时秒数,网络慢可适当调大(默认 60) |
LLM_DEBUG_OUTPUT |
置为 true 打印调试信息,排查 API 问题时开启 |
填完之后:用 doctor.py 一键体检
保存 config.json 后,先跑一次环境诊断再正式调参:
python doctor.py
doctor.py 会检查配置必填字段、LLM API 连通性、串口权限与占用、代理设置等,输出体检报告,能提前拦下绝大多数"启动即失败"的问题。
常见问题速答
Q:填了配置还是报错?
用 python doctor.py 定位;再检查 LLM_API_BASE_URL 是否多了/少了 /v1,BAUD_RATE 是否与固件一致。
Q:只想离线使用?
本地起 Ollama 或 LM Studio,把 LLM_API_BASE_URL 指向本地地址即可。
Q:调着调着变差了?
别慌,PID_LIMITS 护栏 + 保底策略 + 历史最佳参数回退是内建机制,程序设计上就是"优先可用"而不是"盲目激进"。
📌 总结:先填 LLM 4 项,接硬件再补 串口 3 项,跑通之后才考虑 行为 5 项 的微调——按这个顺序,12 个关键字字段就能一次填对。