CLI 配置管理
定义
CLI 配置管理是 Hyper-Extract 用于确定大语言模型与嵌入模型如何连接和运行的配置机制。它涵盖服务商选择、模型名称、API 密钥与 base_url 等连接参数，使同一套命令行工作流能够适配云端 API 或本地部署。
在 Hyper-Extract 中的语境
在 Hyper-Extract 中，配置决定 文档知识抽取 和 知识库索引构建 所需的模型服务从何处获取。CLI 支持 OpenAI、Anthropic、DeepSeek、阿里云百炼以及本地 vLLM 等部署方式；不同服务商可用的默认模型应以相关的服务商兼容性说明为准。
首次初始化与配置文件
首次使用时，推荐运行 he config init。该命令会以交互方式提示用户选择服务商、填写模型名称并输入 API key。
运行 he config init 会自动创建配置文件：Linux 和 macOS 位于 ~/.he/config.toml，Windows 位于 %USERPROFILE%\.he\config.toml。该文件用于保存后续 CLI 调用所需的持久化配置。
配置来源与优先级
除配置文件外，环境变量也可作为配置回退来源，适合临时切换 API key、在 CI/CD 中注入密钥，或避免将密钥硬编码进配置文件。
优先级从高到低为：命令行参数、环境变量、配置文件。因此，命令行标志会覆盖环境变量，而环境变量会覆盖 config.toml 中的同名设置。
LLM 与嵌入模型的重置
可分别清除 LLM 和嵌入模型配置，以恢复默认状态：
he config llm --unset 清除 LLM 配置。
he config embedder --unset 清除嵌入模型配置。
这两个命令只针对各自的配置范围；需要重新指定服务商、模型或密钥时，可再次执行 he config init 或使用相应配置命令。
连接排查
出现“API key not found”时，可重新初始化并显式提供服务商与密钥，例如 he config init -p bailian -k YOUR_API_KEY。
出现模型不存在或 HTTP 404 时，应确认配置的模型名称确实在目标平台可用，而不是仅检查密钥是否存在。
出现 API 连接失败时，先通过 he config llm --show 查看当前 LLM 配置，再校正错误的 base_url。例如阿里云百炼兼容接口可设置为 https://dashscope.aliyuncs.com/compatible-mode/v1。
本地 vLLM 出现“Connection refused”通常表示服务未运行或已停止；可检查 http://localhost:8000/v1/models 与 http://localhost:8001/v1/models，确认服务状态后重启相应服务。
本地推理若发生 CUDA 内存不足，应降低 --gpu-memory-utilization，或改用更小、量化后的模型；这属于运行资源限制，不应仅通过修改 API 连接参数处理。