CLI Configuration Reference 摘要

文档概览

Hyper-Extract CLI 支持以下部署提供商：OpenAI、Anthropic、DeepSeek、阿里云百炼（Alibaba Cloud Bailian）和本地 vLLM。 配置可通过命令行参数、环境变量或配置文件提供；实际生效时遵循明确的覆盖顺序。

关键事实

首次初始化与重置

• 首次使用时，推荐执行交互式初始化命令：he config init。
• 该命令会按提示选择提供商、输入模型名称并输入 API Key。
• 运行 he config init 时，CLI 会自动创建配置文件。
• 可通过 he config llm --unset 清除 LLM 配置并恢复默认状态。
• 可通过 he config embedder --unset 清除嵌入模型（embedder）配置并恢复默认状态。

配置文件位置

• Linux 和 macOS：~/.he/config.toml。
• Windows：%USERPROFILE%\.he\config.toml。
• 配置文件由 he config init 自动创建，而非必须预先手工建立。

配置优先级

配置来源从高到低依次为：

1. 命令行参数（flags）。
2. 环境变量。
3. 配置文件 config.toml。 因此，环境变量会覆盖配置文件中的值，但仍会被同一命令中显式提供的命令行参数覆盖。

重要细节

环境变量的适用场景

环境变量被作为配置回退方式，可用于：

• 临时切换 API Key，而不修改持久化配置。
• 在 CI/CD 环境中注入密钥。
• 避免将密钥硬编码到配置文件中。

模型与提供商

• 各提供商的默认模型信息应参阅 Provider System 的兼容性表。
• 若出现模型不存在或 HTTP 404，应核对已配置的模型名称是否确实由目标平台提供。
• 本地 vLLM 需要对应服务处于运行状态；原文示例检查两个本地端点：http://localhost:8000/v1/models 与 http://localhost:8001/v1/models。

故障排查

缺失 API Key

当出现 API key not found 时，可重新进行提供商配置。例如，阿里云百炼可使用：

he config init -p bailian -k YOUR_API_KEY

模型不存在或 404

当出现 The model does not exist 或 404 时：

• 检查配置的模型名称。
• 确认该模型可在所选平台使用。
• 参阅 Provider System 中的可用模型与兼容性信息。

无法连接 API

当出现 Failed to connect to API 时，先查看当前 LLM 配置：

he config llm --show

如需恢复阿里云百炼兼容模式的地址，可重设 base_url：

he config llm --base-url https://dashscope.aliyuncs.com/compatible-mode/v1

本地 vLLM 拒绝连接

当出现 Connection refused 时，通常表示 vLLM 服务未运行或已经停止。可检查服务端点：

curl http://localhost:8000/v1/models
curl http://localhost:8001/v1/models

若端点不可用，应重启相应服务。

CUDA 显存不足

当出现 CUDA out of memory 时：

• 降低 --gpu-memory-utilization。
• 改用更小的模型。
• 或使用量化版本的模型。

相关条目

• CLI 配置管理
• 配置优先级
• Hyper-Extract
• Provider System