Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

10.5 KB
Raw Blame

CLI 配置参考

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


快速开始

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

=== "OpenAI"

```bash
he config init -p openai -k YOUR_OPENAI_API_KEY
```

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

=== "百炼 (阿里云)"

```bash
he config init -p bailian -k YOUR_BAILIAN_API_KEY
```

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

=== "Anthropic (Claude)"

Anthropic 仅提供 LLM —— 请搭配 OpenAI 兼容嵌入器:

```bash
he config llm -p anthropic -k YOUR_ANTHROPIC_API_KEY
he config embedder -p openai -k YOUR_OPENAI_API_KEY
```

这会创建 `~/.he/config.toml`:
- **LLM**: `claude-opus-4-8` (Anthropic)
- **嵌入模型**: `text-embedding-3-small` (OpenAI)

=== "DeepSeek"

DeepSeek 仅提供 LLM —— 请搭配 OpenAI 兼容嵌入器:

```bash
he config llm -p deepseek -k YOUR_DEEPSEEK_API_KEY
he config embedder -p openai -k YOUR_OPENAI_API_KEY
```

这会创建 `~/.he/config.toml`:
- **LLM**: `deepseek-v4-flash` (DeepSeek,自动关闭思考模式)
- **嵌入模型**: `text-embedding-3-small` (OpenAI)

=== "本地 vLLM"

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

```bash
# 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 / 百炼)"

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

=== "本地 vLLM"

```
┌──────────────────────────────────────────────────────────────────┐
│                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"

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

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

=== "百炼 (阿里云)"

```bash
# 一键配置(默认 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
```

=== "Anthropic (Claude)"

```bash
# LLM 用 Anthropic,Embedding 用 OpenAI
he config llm -p anthropic -k sk-ant-your-key
he config embedder -p openai -k sk-your-openai-key
```

=== "DeepSeek"

```bash
# LLM 用 DeepSeek,Embedding 用 OpenAI
he config llm -p deepseek -k sk-your-key
he config embedder -p openai -k sk-your-openai-key
```

=== "本地 vLLM"

```bash
# 需先启动服务,然后分别配置
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 可以使用不同提供商:

```bash
# 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

在 Linux / macOS 上,he config 会以 0600(仅文件所有者可读写)写入该文件。若已有文件对组或其他用户可读,加载时会给出 warning,下次保存会收紧权限。更推荐用环境变量,而不是把 API key 写入文件。

配置格式

=== "云 API — 百炼"

```toml
[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 = ""
```

=== "本地 vLLM"

```toml
[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"
```

=== "混合部署"

```toml
[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 问题"

**"API key not found"**

```bash
he config init -p bailian -k YOUR_API_KEY
```

**"The model does not exist" / 404**

检查配置的模型名是否在对应平台可用。百炼可用模型见 [Provider 系统](../concepts/provider-system.md)。

**"Failed to connect to API"**

```bash
# 检查配置
he config llm --show

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

=== "本地 vLLM 问题"

**"Connection refused"**

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

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

# 重新启动服务
```

**"CUDA out of memory"**

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

另请参见