AI-Wiki

文档概览

这页文档的核心信息很明确：Hyper-Extract 用统一的 create_client() 接口连接不同的 LLM 与 embedding 提供方，平台切换时“主要只改第一行”或 provider 标识，而不是改整套调用流程。

页面实际覆盖或示例展示的提供方与形态包括：

OpenAI
Alibaba Bailian
Anthropic（仅 LLM；embeddings 需要外配）
本地 vLLM（LLM 与 embedding 服务都可本地起）

文档同时强调，Provider System 不只是“能连上”，还要考虑结构化输出兼容性。尤其是 json_schema、约束解码、with_structured_output、AutoGraph 这类依赖首 token 即进入 JSON 的场景，会受到模型是否输出 <think>...</think>、平台是否支持 json_schema、以及后端是否会过滤 thinking 标签的直接影响。

关键事实

统一接口：所有平台都走 `create_client()`

Hyper-Extract 支持三种连接 LLM 的方式：

OpenAI
Alibaba Bailian
本地 vLLM

在快速开始示例里，还额外展示了 Anthropic 的接法。文档的明确说法是：所有方式都使用同一个 create_client() 接口，差异主要体现在第一行配置不同。

这意味着对调用方来说，Provider System 的抽象重点不是为每个平台分别写一套客户端，而是统一由 create_client() 返回 llm, emb，然后在 provider 名称、模型描述串、API key 或 endpoint 上做切换。

Quick Start 的各平台示例

文档给出的快速开始代码如下，其重点不是完整业务逻辑，而是展示 llm 与 embedder 的写法差异：

OpenAI

from hyperextract import create_client

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

这里使用最简写法，把 provider 直接写成 "openai"，同时传入 api_key。

Bailian

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

Bailian 与 OpenAI 的示例形式几乎一致，体现的正是统一接口设计：切换平台时，核心变化就是把 provider 标识从 openai 改成 bailian。

Anthropic（Claude）

llm, emb = create_client(
 llm="anthropic",
 embedder="openai:text-embedding-3-small",
)

这个示例有几个必须保留的细节：

Anthropic 在 Hyper-Extract 里是“LLM only”的接法。
文档明确说明：Anthropic 没有 embeddings API，因此必须把 Anthropic 的 LLM 与一个 OpenAI-compatible 的 embedder 配对使用。
示例里 embedding 侧明确写成 openai:text-embedding-3-small，这不是泛泛而谈，而是具体的推荐写法。
llm="anthropic" 时，默认模型是 claude-opus-4-8。
如果要改模型，可用 "anthropic:<model>" 的形式覆盖默认值。

相关环境变量键名也被文档明确写出：

LLM 侧使用 ANTHROPIC_API_KEY，或 CLAUDE_API_KEY
embeddings 侧使用 OPENAI_API_KEY

也就是说，如果采用 Anthropic 方案，运行环境至少要同时准备两类凭证：一类给 Claude，一类给 OpenAI-compatible embeddings。

本地 vLLM

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

这个示例展示了本地 provider 字符串的完整形态：

LLM 写法：vllm:<model>@<endpoint>
embedding 写法：vllm:<model>@<endpoint>

文档中的具体实例分别是：

vllm:Qwen3.5-9B@http://localhost:8000/v1
vllm:bge-m3@http://localhost:8001/v1

api_key="dummy" 也不是可忽略细节，它说明本地 OpenAI-compatible 服务接口可能仍要求请求格式里带 key，即使这个 key 只是占位值。

重要细节

Anthropic 的限制：没有 embeddings API

文档明确指出，Anthropic 只能承担 LLM 角色，不能单独提供 embeddings。因此在 Hyper-Extract 中，Anthropic 不是“全家桶 provider”，而是需要与 OpenAI-compatible embedder 组合使用。

可直接落地的组合方式是：

llm="anthropic" 或 llm="anthropic:<model>"
embedder="openai:text-embedding-3-small"

对应的凭证配置是：

ANTHROPIC_API_KEY 或 CLAUDE_API_KEY：供 LLM 使用
OPENAI_API_KEY：供 embeddings 使用

这也是 Provider System 页面里最明确的“异构组合”示例：LLM 与向量模型不一定来自同一云厂商，但只要满足 Hyper-Extract 的 provider 约定，就能通过统一接口组合起来。

Bailian 的结构化输出兼容性限制

文档在“Verified Model Compatibility”下给了非常具体的警告，尤其针对 Alibaba Bailian 用户：

qwen-max 不支持 json_schema
deepseek-v3 不支持 json_schema

出现下列症状时，文档建议直接换模型：

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

推荐的替代模型是：

qwen-plus
qwen-turbo
deepseek-r1

这里的重点不是“有些模型效果不好”，而是它们与 json_schema 这类结构化输出机制存在明确不兼容。对于依赖 with_structured_output 或自动解析 JSON 的流程，这属于硬边界，不是简单调 prompt 就能稳定绕过的问题。

DeepSeek-R1 经由 Bailian 可用，但其他渠道未必

文档特别强调：DeepSeek-R1 via Bailian is verified to work。

它可用的原因不是 DeepSeek-R1 天然没有 thinking 输出，而是 Bailian 后端会过滤 <think> 标签。正因为这些标签被后端去掉了，所以：

AutoGraph 可以正常工作
with_structured_output 可以正常工作

这条信息很关键，因为它说明“模型本身”与“接入渠道”都会影响结构化输出兼容性。同一个 DeepSeek-R1：

通过 Bailian 访问：已验证可用
通过其他渠道访问：thinking 输出仍可能造成问题

文档的原意是提醒使用者，不要把某一条 provider 路径上的成功经验，误认为模型在所有托管渠道上都同样稳定。

本地 vLLM 部署推荐：使用非 thinking 模型

在本地 vLLM 部署部分，文档给出的总建议非常明确：

优先使用 non-thinking models。

原因也写得很具体：thinking 模型会输出 <think>...</think> 标签，而这会与 constrained decoding 的要求发生冲突。后者要求模型从第一个 token 开始就进入 JSON 格式输出。

换句话说，如果结构化输出要求“首 token 即 JSON”，而模型先吐出 <think>，那约束解码链路就会被破坏。这不是简单的结果污染，而是协议级别的首 token 不满足要求。

文档举的典型例子是 Qwen3.5 的 thinking mode，并明确要求在部署 Qwen3.5-9B 时关闭它。

Qwen3.5-9B 关闭 thinking mode 的具体参数

关闭参数必须写成：

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

这不是建议性的伪代码，而是出现在 vLLM 启动命令中的实际参数。文档将它同时放在“Start LLM Service”的完整命令里，并在 Recommendations 中再次强调。

本地 vLLM 的 LLM 服务启动命令

文档给出的 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

这个命令中值得保留的具体参数包括：

模型路径：/path/to/qwen3.5-9b-gptq-marlin
对外模型名：Qwen/Qwen3.5-9B
--quantization gptq_marlin
--dtype bfloat16
--max-model-len 8192
--gpu-memory-utilization 0.90
关闭 thinking：--default-chat-template-kwargs '{"enable_thinking": false}'
端口：8000
API key：dummy

这些参数一方面说明了文档作者实测的部署方式，另一方面也为本地 provider 字符串中的 endpoint http://localhost:8000/v1 提供了对应来源。

本地 vLLM 的 Embedding 服务启动命令

embedding 服务的示例命令是：

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

这里也有几个明确细节：

使用模型：BAAI/bge-m3
任务类型必须指定为 embed
dtype 是 float16
max-model-len 是 8192
端口是 8001

这与 Quick Start 中的 embedder="vllm:bge-m3@http://localhost:8001/v1" 一一对应。

Docker 示例

文档还给了一个 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

这个 Docker 例子没有像前面的完整命令那样显式给出关闭 thinking 的参数，因此如果目标是与 Hyper-Extract 的结构化输出链路配合，仍应把 Recommendations 中的 non-thinking 约束视为更高优先级。

量化方案建议：优先 GPTQ-Marlin，不优先 AWQ

文档在建议部分还给出一个额外的部署兼容性建议：

优先 GPTQ-Marlin
不优先 AWQ

原因是 AWQ 与 vLLM 0.21.0 存在兼容性问题。

这条建议虽然不直接属于 provider 选择，但它会影响本地 vLLM 路线是否稳定可用，因此属于 Provider System 页面中的重要运维边界条件。

可操作结论

如果只想快速切换云端 provider，最直接的做法是维持同一套 create_client() 调用习惯，只替换 provider 标识：

OpenAI：create_client("openai", api_key="...")
Bailian：create_client("bailian", api_key="...")

如果使用 Anthropic，则要意识到它不是“一站式 LLM+embedding”提供方，必须外配 embedding，并配置两类 API key。

如果依赖结构化输出：

Bailian 上避免 qwen-max、deepseek-v3 这类不支持 json_schema 的模型
出现 messages must contain the word 'json' 或非 JSON 输出时，优先切换到 qwen-plus、qwen-turbo、deepseek-r1
DeepSeek-R1 通过 Bailian 已验证可用，但不能自动推广到其他接入渠道
本地 vLLM 一定优先用 non-thinking 模型或显式关闭 thinking mode

如果走本地 vLLM：

LLM 与 embedding 可以分别在 8000、8001 端口启动
provider 字符串应写成 vllm:<model>@<endpoint>
Qwen3.5-9B 必须注意 --default-chat-template-kwargs '{"enable_thinking": false}'
量化方案优先 gptq_marlin，避免 AWQ 与 vLLM 0.21.0 的兼容问题

Provider System - Hyper-Extract 摘要

文档概览

关键事实

统一接口：所有平台都走 `create_client()`

Quick Start 的各平台示例

OpenAI

Bailian

Anthropic（Claude）

本地 vLLM

重要细节

Anthropic 的限制：没有 embeddings API

Bailian 的结构化输出兼容性限制

DeepSeek-R1 经由 Bailian 可用，但其他渠道未必

本地 vLLM 部署推荐：使用非 thinking 模型

Qwen3.5-9B 关闭 thinking mode 的具体参数

本地 vLLM 的 LLM 服务启动命令

本地 vLLM 的 Embedding 服务启动命令

Docker 示例

量化方案建议：优先 GPTQ-Marlin，不优先 AWQ

可操作结论

相关条目

Provider System - Hyper-Extract 摘要

文档概览

关键事实

统一接口：所有平台都走 create_client()

Quick Start 的各平台示例

OpenAI

Bailian

Anthropic（Claude）

本地 vLLM

重要细节

Anthropic 的限制：没有 embeddings API

Bailian 的结构化输出兼容性限制

DeepSeek-R1 经由 Bailian 可用，但其他渠道未必

本地 vLLM 部署推荐：使用非 thinking 模型

Qwen3.5-9B 关闭 thinking mode 的具体参数

本地 vLLM 的 LLM 服务启动命令

本地 vLLM 的 Embedding 服务启动命令

Docker 示例

量化方案建议：优先 GPTQ-Marlin，不优先 AWQ

可操作结论

相关条目

统一接口：所有平台都走 `create_client()`