W
AI-Wiki
CONCEPT

Hyper-Extract Provider Configuration

定义

Hyper-Extract Provider Configuration 是 Hyper-Extract 中把不同模型提供方接入同一抽取流程的配置机制。 它的直接作用，是为抽取任务提供两类运行时依赖：llm_client 与 embedder client。 借助这套机制，调用方可以在 OpenAI、阿里云百炼（Bailian）和本地 vLLM 之间切换，而不需要重写抽取任务本身。

在本文档中的语境

本文档讨论的不是抽取规则如何设计，而是“同一个抽取任务如何更换后端 provider”。 来源给出的统一示例明确强调：三种平台运行的是同一个 extraction task，真正变化的只有最前面的 client setup。 也就是说，Provider Configuration 解决的是接入层和初始化层问题，不改变任务逻辑层。

不变量与变量

不变量

在统一示例中，以下部分保持不变：

  • 抽取任务目标不变，仍然是 Extract people and their relationships。
  • AutoGraph 的主体配置不变。
  • 传入 AutoGraph 的节点键提取器、边键提取器、边中节点提取器不变。
  • 输入文本与执行方式不变，仍然通过 graph.parse(text) 解析文本。
  • 结果读取方式不变，仍然可以通过 len(graph.nodes) 和 len(graph.edges) 查看节点与边数量。

统一示例中的固定任务代码可以概括为：

  • 使用 AutoGraph( 创建图抽取任务。
  • instruction="Extract people and their relationships"。
  • node_key_extractor=lambda n: n.name。
  • edge_key_extractor=lambda e: (e.source, e.target, e.type)。
  • nodes_in_edge_extractor=lambda e: (e.source, e.target)。
  • 示例文本为 "Zhang San founded ByteDance. Li Si serves as CEO."。
  • 调用 graph.parse(text) 后打印节点数和边数。

变量

变化的部分只有 client setup，也就是如何拿到 llm 和 emb。 这部分差异完全由 provider 配置承担，而不是由 AutoGraph Extraction Task 的图抽取逻辑承担。

支持的 provider 范围

来源页明确列出三类 provider：

  • OpenAI
  • Bailian（Alibaba Cloud）
  • 本地 vLLM

这意味着 Hyper-Extract 至少在该配置指南中，把远程托管 API 与本地部署模型都纳入了同一套客户端配置接口。

Python API 路径：create_client()

基本机制

在 Python API 中，最直接的方式是调用 create_client()，并让它直接返回 llm, emb。 随后再把这两个对象传入 AutoGraph：

  • llm 传给 llm_client
  • emb 传给 embedder

这种方式的核心特征是：配置在代码里显式完成，不依赖预先存在的本地配置文件。

OpenAI 示例

OpenAI 的示例是：

  • 导入 create_client, AutoGraph
  • 调用 llm, emb = create_client("openai", api_key="sk-xxx")

这里的含义是，使用 openai 这个 provider 标识，并通过 api_key 完成认证。

Bailian 示例

阿里云百炼的示例是：

  • 调用 llm, emb = create_client("bailian", api_key="sk-xxx")

来源还给出一个模型覆盖写法：

  • create_client("bailian:qwen3.6-plus", api_key="sk-xxx")

这说明：

  • 只写 "bailian" 时，会使用该 provider 的预设默认值。
  • 写成 "bailian:qwen3.6-plus" 时，会覆盖 LLM 模型，但仍沿用该 provider 预设的 embedder。

本地 vLLM 示例

本地 vLLM 的示例不是单个 provider 名，而是分别指定 LLM 与 embedder：

  • llm="vllm:Qwen3.5-9B@http://localhost:8000/v1"
  • embedder="vllm:bge-m3@http://localhost:8001/v1"
  • api_key="dummy"

这里有几个细节值得注意：

  • 本地 vLLM 示例把 LLM 与 embedding 服务拆成两个地址。
  • LLM 地址是 http://localhost:8000/v1。
  • embedding 地址是 http://localhost:8001/v1。
  • 即使是本地服务，接口层仍然接收 api_key 参数，示例值为 dummy。这表示调用形式保持统一，但该值在本地场景下更多是占位用途。

字符串简写格式

create_client() 支持紧凑的字符串简写，用于快速配置。来源列出三种格式：

provider

格式：provider 示例："bailian" 结果：使用该 provider 预设的 LLM 与 embedder 默认值。

provider:model

格式：provider:model 示例："bailian:qwen3.6-plus" 结果：覆盖 LLM 模型，但保持预设 embedder 不变。

provider:model@url

格式：provider:model@url 示例："vllm:Qwen3.5-9B@localhost:8000/v1" 结果：通过 provider、模型名与 URL 进行完整手动指定。

这套简写机制的意义，在于把常见配置压缩成一个字符串表达；它与 Hyper-Extract Client String Shorthand 直接相关。

文件配置路径：he config init + get_client()

初始化配置文件

如果不希望在代码里手动传 provider、URL 或 key，可以先通过 CLI 初始化配置。 来源说明的入口命令是 he config init。 初始化完成后，相关配置会被后续 Python API 读取。

读取配置文件

文件配置方式下，代码可以改为：

  • from hyperextract import get_client, AutoGraph
  • llm, emb = get_client()
  • get_client() 会读取 ~/.he/config.toml
  • 再把返回的 llm, emb 传给 AutoGraph(..., llm_client=llm, embedder=emb)

这条路径的重点是：Python 代码不再负责描述 provider 细节，而是从统一配置文件中取回已经定义好的客户端。

CLI 等价配置

来源给出了与 Python 初始化相对应的 CLI 命令。它们不是另一套独立机制，而是达到同一目标的另一种入口。

OpenAI

命令：he config init -p openai -k sk-xxx

Bailian

命令：he config init -p bailian -k sk-xxx

vLLM

命令：he config init 然后在交互过程中选择 local vLLM。

混合配置

来源还给出一个混合场景：

  • LLM 使用 Bailian
  • Embedder 使用 vLLM

对应命令是：

  • he config llm -p bailian -k sk-xxx
  • he config embedder -p vllm -u http://localhost:8001/v1 -k dummy

这说明 Provider Configuration 不要求 LLM 与 embedder 必须来自同一 provider。 至少在文档示例里，二者可以分别配置，并组合成一个混合后端。

CLI 与 Python 配置的等价关系

CLI 初始化与编程式创建，本质上都服务于同一个目标：得到可注入 AutoGraph 的 llm 与 emb 客户端。 差别只在配置承载位置：

  • create_client() 把配置直接写在代码里。
  • he config init、he config llm、he config embedder 先把配置写入本地文件，再由 get_client() 读取。

因此，两条路径在抽取任务层面是等价的。 无论采用哪种方式，只要最终得到兼容的 llm_client 和 embedder，后续 AutoGraph 初始化与 graph.parse(text) 调用都不需要改变。

细节与边界

  • 该机制关注的是 provider 接入与客户端创建，不是任务 schema 或抽取规则设计。
  • 文档明确覆盖的 provider 只有 OpenAI、Bailian 和本地 vLLM；不能从该页推出更多 provider 也受同等支持。
  • 统一示例证明“同一任务、不同 client setup”是官方主张的使用方式。
  • provider:model 只明确说明覆盖 LLM 模型，并保留预设 embedder；文档没有在该页进一步说明 embedder 模型覆盖的更多字符串变体。
  • 本地 vLLM 场景中，LLM 与 embedder 可以指向不同本地服务地址，说明两者在实现上是可分离配置的。
  • 混合配置示例只明确展示了“LLM=Bailian、Embedder=vLLM”这一方向，不能据此自动推断所有任意组合都在该页被完整说明。

相关条目