Hyper-Extract Provider System

定义

Hyper-Extract Provider System 是 Hyper-Extract 面向多种模型服务后端的统一接入机制。它的作用不是为每一家厂商分别设计一套独立流程，而是把不同云端 API 与本地推理服务统一为同一种客户端创建方式：通过 create_client() 一次性创建出抽取流程需要的模型客户端。

在这个体系里，使用者通常主要改变的是 provider 声明、模型标识，或服务 endpoint，而不是改动整套调用逻辑。也就是说，业务侧代码不需要因为后端从 OpenAI 换到阿里百炼，或从云端换到本地 vLLM，就重新写一遍调用流程。

在 Hyper-Extract 中的语境

Hyper-Extract 的抽取流程不只依赖聊天模型。它通常同时需要：

• 一个负责理解、推理、生成结构化结果的 LLM 客户端。
• 一个负责向量化文本、支持检索或相似度相关能力的 embedding 客户端。

因此 provider system 的核心接口不是只返回一个模型对象，而是返回两个对象：llm, emb。这说明在 Hyper-Extract 的设计里，provider 适配从一开始就同时考虑了生成模型与 embedding 模型，而不是把 embeddings 当作事后附加功能。

统一接口的关键机制

create_client() 是统一入口

典型用法是：

from hyperextract import create_client

llm, emb = create_client("openai", api_key="sk-xxx")

这个接口的设计重点是“统一创建方式”。同一份上层调用代码，可以在不同 provider 间切换；差异主要体现在第一行的 provider 或更细的模型声明上。

返回值固定为 llm, emb

无论后端来自云端 API 还是本地推理服务，调用约定都尽量保持一致：

llm, emb = create_client(...)

这意味着 provider system 处理的不只是聊天补全接口，还包括 embedding 服务的配套接入。对于 Hyper-Extract 这种需要结构化抽取、向量化与多阶段处理配合的系统，这一点是基础设计，而不是边缘特性。

支持的后端类型与示例

原始文档给出的快速开始示例覆盖了四类典型后端：OpenAI、阿里百炼、Anthropic、本地 vLLM。

OpenAI

OpenAI 是最直接的云端接入方式之一：

llm, emb = create_client("openai", api_key="sk-xxx")

这里调用者只声明 openai，其余由 provider system 按 OpenAI 体系完成 LLM 与 embedding 客户端的组装。

阿里百炼

阿里百炼同样通过相同接口接入：

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

从调用形式上看，和 OpenAI 基本一致。这正体现了 provider system 的目标：切换后端时，优先变更 provider 声明，而不是变更整套使用方式。

Anthropic

Anthropic 在这个体系里有一个明确边界：只提供 LLM，不提供 embeddings。因此它不能单独满足 Hyper-Extract 的完整客户端需求，必须搭配一个 OpenAI-compatible 的 embedding 服务。

文档中的示例是：

llm, emb = create_client(
 llm="anthropic",  # default model: claude-opus-4-8
 embedder="openai:text-embedding-3-small",
)

这里有几个关键事实：

• Anthropic 侧负责 LLM。
• embedding 侧明确交给 openai:text-embedding-3-small。
• 默认模型是 claude-opus-4-8。
• 如需覆盖默认模型，可以使用 anthropic:<model> 的形式指定。

凭证要求也分成两部分：

• LLM 需要 ANTHROPIC_API_KEY，或 CLAUDE_API_KEY。
• embeddings 需要 OPENAI_API_KEY。

因此，Anthropic 在 Hyper-Extract Provider System 中不是“完整 provider 一站式闭环”，而是“LLM provider + 外部 embedder”的组合场景。

本地 vLLM

本地 vLLM 是 provider system 统一本地推理服务的典型例子。文档中的示例把 LLM 与 embedding 服务分别指向两个本地 OpenAI-compatible endpoint：

llm, emb = create_client(
 llm="vllm:Qwen3.5-9B@http://localhost:8000/v1",
 embedder="vllm:bge-m3@http://localhost:8001/v1",
 api_key="dummy",
)

这里体现出本地接入的几个关键约束：

• LLM 与 embedding 可以是两个独立服务。
• 两者都通过 vllm:<model>@<endpoint> 这样的声明绑定模型与地址。
• 示例中 LLM endpoint 为 http://localhost:8000/v1。
• embedding endpoint 为 http://localhost:8001/v1。
• API key 可以是占位用的 dummy。

与结构化输出能力的关系

Hyper-Extract Provider System 不只是“能不能连上模型”的问题，它还直接关系到 结构化输出兼容性。

Hyper-Extract 的结构化抽取依赖模型按约束输出 JSON，某些流程会要求 json_schema 能力。如果 provider 或具体模型不支持 json_schema，就会直接影响结构化抽取结果，表现为报错、输出非 JSON，或无法稳定配合约束解码。

百炼中的已知兼容性边界

文档明确指出，阿里百炼用户在使用以下模型时存在结构化输出问题：

• qwen-max
• deepseek-v3

这两个模型不支持 json_schema。实际症状包括：

• 报错 messages must contain the word 'json'。
• 返回结果不是 JSON。

如果遇到这些问题，文档给出的替代方案是切换到以下模型：

• qwen-plus
• qwen-turbo
• deepseek-r1

这说明 provider system 的选择粒度不只是“选哪家 provider”，还包括“在同一 provider 下选哪个模型”。模型能力差异会直接决定 Hyper-Extract 的结构化抽取链路是否可用。

本地 vLLM 的部署细节与边界

provider system 虽然统一了接口，但本地部署仍有明确的运行约束。原文给出了 LLM 服务、embedding 服务和 Docker 启动示例。

启动 LLM 服务

vllm serve /path/to/qwen3.5-9b-gptq-marlin \
 --served-model-name Qwen/Qwen3.5-9B \
 --trust-remote-code \
 --quantization gptq_marlin \
 --dtype bfloat16 \
 --max-model-len 8192 \
 --gpu-memory-utilization 0.90 \
 --default-chat-template-kwargs '{"enable_thinking": false}' \
 --port 8000 \
 --api-key dummy

这个示例包含几项重要参数：

• 服务模型名设为 Qwen/Qwen3.5-9B。
• 量化方式使用 gptq_marlin。
• dtype 为 bfloat16。
• max-model-len 为 8192。
• GPU 显存利用率设为 0.90。
• 端口为 8000。
• API key 为 dummy。
• 显式关闭 thinking mode：{"enable_thinking": false}。

启动 Embedding 服务

vllm serve BAAI/bge-m3 \
 --task embed \
 --dtype float16 \
 --max-model-len 8192 \
 --port 8001

这说明 embedding 服务与 LLM 服务可以独立启动，并使用不同模型、任务模式和端口。其中：

• embedding 模型为 BAAI/bge-m3。
• 任务类型明确是 embed。
• dtype 为 float16。
• 端口为 8001。
• max-model-len 同样设为 8192。

Docker 示例

docker run --runtime nvidia --gpus all \
 --ipc=host \
 -v ~/.cache/huggingface:/root/.cache/huggingface \
 -p 8000:8000 \
 vllm/vllm-openai:latest \
 --model Qwen/Qwen3.5-9B \
 --trust-remote-code

这个示例说明 provider system 所对接的本地 vLLM，并不要求特殊私有协议；它依赖的是 vLLM 提供的 OpenAI-compatible 服务形态。

推荐与例外

本地优先使用非 thinking 模型

文档明确建议：本地 vLLM 部署优先使用 non-thinking models。

原因不是抽象的“效果更稳定”，而是一个非常具体的结构化输出冲突：thinking 模型会输出 <think>...</think> 标签，而约束解码要求模型从第一个 token 开始就输出 JSON。这两者会直接冲突。

对于 Qwen3.5-9B，本地部署时应通过以下参数关闭 thinking mode：

--default-chat-template-kwargs '{"enable_thinking": false}'

这条建议与 结构化输出兼容性 直接相关，因为一旦前缀先吐出思维标签，with_structured_output 或类似的结构化抽取流程就可能失败。

DeepSeek-R1 经百炼接入已验证可用

文档特别指出：通过百炼访问 DeepSeek-R1 已验证可用。

原因在于百炼后端会过滤掉 <think> 标签，因此 AutoGraph 和 with_structured_output 能正常工作。

但这个结论有明确边界：如果通过“其他渠道”访问 DeepSeek-R1，thinking 输出仍可能造成问题。也就是说，是否可用于结构化抽取，不只取决于模型名字本身，还取决于 provider 在后端是否做了额外处理。

量化建议：优先 GPTQ-Marlin 而不是 AWQ

对于本地 vLLM 部署，文档建议优先使用 GPTQ-Marlin，而不是 AWQ。原因是 AWQ 与 vLLM 0.21.0 存在兼容性问题。

这类细节虽然看似属于部署层，但会间接影响 provider system 的实际可用性：接口再统一，如果底层量化方案与运行时不兼容，Hyper-Extract 也无法稳定获得可用的 llm, emb 客户端。

理解这个系统时应把握的重点

可以把 Hyper-Extract Provider System 理解为三层统一：

1. 接入统一：不论是 OpenAI、百炼、Anthropic，还是本地 vLLM，都通过 create_client() 进入系统。
2. 对象统一：统一返回 llm, emb 两个客户端，而不是只关心聊天模型。
3. 能力统一但需校验边界：表面接口一致，不代表底层能力完全一致，尤其是 json_schema、thinking 输出、embeddings 支持情况，都会影响结构化抽取。

因此，在 Hyper-Extract 里选择 provider 时，不能只看“是否能调用”；还要看：

• 是否同时具备 LLM 与 embeddings 支持。
• 如果没有，是否能像 Anthropic 那样与其他 embedder 组合。
• 是否支持 json_schema。
• 是否会输出 <think> 标签破坏受约束 JSON 生成。
• 本地部署时量化方案与 vLLM 版本是否兼容。

相关条目

• Hyper-Extract
• Provider System - Hyper-Extract 摘要
• 结构化输出兼容性
• 本地 vLLM 部署约束
• OpenAI
• 阿里百炼
• Anthropic
• vLLM