CLI 配置参考¶

Hyper-Extract CLI 的配置指南，支持 OpenAI、阿里云百炼 和 本地 vLLM 三种部署方式。

快速开始¶

选择你的部署方式，按步骤完成配置。

OpenAI百炼 (阿里云)本地 vLLM

he config init -p openai -k YOUR_OPENAI_API_KEY

这会创建 ~/.he/config.toml，使用 OpenAI 预设： - LLM: gpt-4o-mini - 嵌入模型: text-embedding-3-small

he config init -p bailian -k YOUR_BAILIAN_API_KEY

这会创建 ~/.he/config.toml，使用百炼预设： - LLM: qwen3.6-plus - 嵌入模型: text-embedding-v4

需先启动 LLM 和 Embedding 两个服务，然后分别配置：

# LLM 服务
he config llm -p vllm \
  -u http://localhost:8000/v1 \
  -k dummy \
  -m Qwen/Qwen3.5-9B

# Embedding 服务
he config embedder -p vllm \
  -u http://localhost:8001/v1 \
  -k dummy \
  -m BAAI/bge-m3

验证配置¶

he config show

云 API (OpenAI / 百炼)本地 vLLM

┌─────────────────────────────────────────────────────────────┐
│              Hyper-Extract Configuration                    │
├──────────┬──────────┬─────────────────────┬────────────┬────┤
│ Service  │ Provider │ Model               │ API Key    │ ...│
├──────────┼──────────┼─────────────────────┼────────────┼────┤
│ LLM      │ bailian  │ qwen3.6-plus        │ sk-xxxx... │ ...│
│ Embedder │ bailian  │ text-embedding-v4   │ sk-xxxx... │ ...│
└──────────┴──────────┴─────────────────────┴────────────┴────┘

┌──────────────────────────────────────────────────────────────────┐
│                Hyper-Extract Configuration                       │
├──────────┬──────────┬─────────────────────┬──────────┬───────────┤
│ Service  │ Provider │ Model               │ API Key  │ Base URL  │
├──────────┼──────────┼─────────────────────┼──────────┼───────────┤
│ LLM      │ vllm     │ Qwen/Qwen3.5-9B     │ dummy... │ localhost…│
│ Embedder │ vllm     │ BAAI/bge-m3         │ dummy... │ localhost…│
└──────────┴──────────┴─────────────────────┴──────────┴───────────┘

CLI 命令参考¶

命令概览¶

命令	常用参数	描述
`he config init`	`-p, --provider` — 提供商 preset `-k, --api-key` — API 密钥 `-u, --base-url` — 自定义 API 地址	初始化配置（首次使用）
`he config llm`	`-p, --provider` — 提供商 `-m, --model` — 模型名称 `-k, --api-key` — API 密钥 `-u, --base-url` — 自定义 API 地址 `--show` — 查看当前配置 `--unset` — 清除配置	配置 LLM
`he config embedder`	`-p, --provider` — 提供商 `-m, --model` — 模型名称 `-k, --api-key` — API 密钥 `-u, --base-url` — 自定义 API 地址 `--show` — 查看当前配置 `--unset` — 清除配置	配置嵌入模型
`he config show`	—	查看完整配置

常见用法示例¶

交互式初始化（推荐首次使用）：

he config init
# 按提示选择提供商、输入模型名和 API 密钥

查看 LLM 配置：

he config llm --show

清除配置（重置为默认值）：

he config llm --unset
he config embedder --unset

分平台配置示例¶

OpenAI百炼 (阿里云)本地 vLLM混合部署

# 一键配置
he config init -p openai -k sk-your-key

# 或换模型
he config llm -p openai -k sk-your-key -m gpt-4o

# 一键配置（默认 qwen3.6-plus + text-embedding-v4）
he config init -p bailian -k sk-your-key

# 或换模型
he config llm -p bailian -k sk-your-key -m qwen-plus

# 需先启动服务，然后分别配置
he config llm -p vllm \
  -u http://localhost:8000/v1 \
  -k dummy \
  -m Qwen/Qwen3.5-9B

he config embedder -p vllm \
  -u http://localhost:8001/v1 \
  -k dummy \
  -m BAAI/bge-m3

LLM 和 Embedder 可以使用不同提供商：

# LLM 用百炼，Embedding 用本地 vLLM
he config llm -p bailian -k sk-your-key
he config embedder -p vllm \
  -u http://localhost:8001/v1 \
  -k dummy \
  -m BAAI/bge-m3

# 或 LLM 用本地，Embedding 用百炼
he config llm -p vllm \
  -u http://localhost:8000/v1 \
  -k dummy \
  -m Qwen/Qwen3.5-9B
he config embedder -p bailian -k sk-your-key

配置文件详解¶

运行 he config init 时会自动创建 ~/.he/config.toml。

文件位置¶

Linux/macOS: ~/.he/config.toml
Windows: %USERPROFILE%\.he\config.toml

配置格式¶

云 API — 百炼本地 vLLM混合部署

[llm]
provider = "bailian"
model = "qwen3.6-plus"
api_key = "sk-your-api-key"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"

[embedder]
provider = "bailian"
model = "text-embedding-v4"
api_key = ""
base_url = ""

[llm]
provider = "vllm"
model = "Qwen/Qwen3.5-9B"
api_key = "dummy"
base_url = "http://localhost:8000/v1"

[embedder]
provider = "vllm"
model = "BAAI/bge-m3"
api_key = "dummy"
base_url = "http://localhost:8001/v1"

[llm]
provider = "bailian"
model = "qwen3.6-plus"
api_key = "sk-your-api-key"
base_url = ""

[embedder]
provider = "vllm"
model = "BAAI/bge-m3"
api_key = "dummy"
base_url = "http://localhost:8001/v1"

配置项说明¶

节	键	描述	默认值
`[llm]`	`provider`	提供商 preset	—
`[llm]`	`model`	LLM 模型名称	取决于 provider preset
`[llm]`	`api_key`	API 密钥	必填
`[llm]`	`base_url`	API 基础 URL	取决于 provider preset
`[embedder]`	`provider`	提供商 preset	—
`[embedder]`	`model`	嵌入模型名称	取决于 provider preset
`[embedder]`	`api_key`	API 密钥（留空继承 llm）	—
`[embedder]`	`base_url`	API 基础 URL（留空继承 llm）	—

不同 provider 的默认模型见 Provider 系统兼容性表格。

环境变量¶

以下环境变量可作为配置的备选方案：

变量	映射到	示例
`OPENAI_API_KEY`	`llm.api_key`, `embedder.api_key`	`sk-...`
`OPENAI_BASE_URL`	`llm.base_url`	`https://api.openai.com/v1`

优先级说明： 环境变量优先级高于配置文件，低于命令行参数。

使用场景： - 临时切换 API 密钥 - CI/CD 环境中注入密钥 - 不想在配置文件中硬编码密钥

故障排除¶

云 API 问题本地 vLLM 问题

"API key not found"

he config init -p bailian -k YOUR_API_KEY

"The model does not exist" / 404

检查配置的模型名是否在对应平台可用。百炼可用模型见 Provider 系统。

"Failed to connect to API"

# 检查配置
he config llm --show

# 重新设置 base_url
he config llm --base-url https://dashscope.aliyuncs.com/compatible-mode/v1

"Connection refused"

vLLM 服务未启动或服务已停止：

# 检查服务是否运行
curl http://localhost:8000/v1/models
curl http://localhost:8001/v1/models

# 重新启动服务

"CUDA out of memory"

降低 --gpu-memory-utilization 或换用更小的模型/量化版本。

另请参见¶

he config — 详细的配置命令说明
Provider 系统 — 完整模型兼容性列表
安装指南 — 初始安装步骤