Provider 系统¶
Hyper-Extract 支持以下接入方式:OpenAI、Anthropic、Google Gemini、阿里云百炼、DeepSeek、OrcaRouter、Atlas Cloud、Runcrate、Cerebras、Mistral AI、Moonshot (Kimi)、Cheaper Inference、CloudGPU、llm.buzz、LLMTR、本地 Ollama、本地 vLLM。统一使用 create_client() 接口,仅需修改第一行。
已验证模型兼容性¶
云端 API¶
| 平台 | 模型 | 函数调用 | 兼容性 | 备注 |
|---|---|---|---|---|
| OpenAI | gpt-4o / gpt-4o-mini / gpt-5 | ✅ | ✅ | 官方原生支持,推荐 |
| API Route | gpt-6.1-sol | ✅ | ✅ | OpenAI 兼容 LLM 预设,嵌入模型需单独配置。密钥:API_ROUTE_API_KEY。配置指南 |
| Anthropic | claude-opus-4-8 / claude-sonnet-4-6 / claude-haiku-4-5 | ✅(工具调用) | ✅ | 仅 LLM——无嵌入接口(请搭配 OpenAI 兼容嵌入器)。需 hyperextract[anthropic] |
| Google Gemini | gemini-3.8-flash / gemini-2.5-flash / gemini-2.5-pro | ✅(工具调用) | ✅ | 仅 LLM——本仓库无成熟嵌入路径(请搭配 OpenAI 兼容嵌入器)。需 hyperextract[google]。密钥:GOOGLE_API_KEY 或 GEMINI_API_KEY。别名:gemini |
| DeepSeek | deepseek-v4-flash / deepseek-v4-pro | ✅ | ✅ | OpenAI 兼容。V4 模型默认开启"thinking"模式,Hyper-Extract 会自动关闭以保证结构化抽取可用。仅 LLM——无嵌入接口。密钥:DEEPSEEK_API_KEY |
| OrcaRouter | orcarouter/auto、openai/gpt-4o-mini、anthropic/claude-haiku-4-5、deepseek/...、gemini/... |
✅ | ✅ | OpenAI 兼容网关,用同一端点和密钥路由 OpenAI、Anthropic、Google、DeepSeek、Qwen、MiniMax、xAI 等 150+ 模型。密钥:ORCAROUTER_API_KEY |
| Atlas Cloud | deepseek-ai/deepseek-v4-flash、deepseek-ai/deepseek-v4-pro、moonshotai/kimi-k3、qwen/qwen3.5-plus、openai/gpt-5.5、anthropic/claude-sonnet-4.6 |
✅ | ✅ | OpenAI 兼容网关,模型 id 带厂商前缀,覆盖 DeepSeek、智谱、月之暗面、Qwen、MiniMax、OpenAI、Anthropic、Google 等。仅 LLM —— 无嵌入 API。glm-5.x 不接受结构化抽取使用的强制 tool_choice,请换其他模型。密钥:ATLASCLOUD_API_KEY |
| Runcrate | deepseek-ai/DeepSeek-V4.1-Flash、openai/gpt-oss-120b |
✅ | ✅ | OpenAI 兼容 API,提供带厂商前缀 id 的开放模型。同时提供嵌入(BAAI/bge-m3,1024 维),一个密钥即可覆盖 LLM 与嵌入器。开放模型可通过 GitHub 账号免费使用。测试中 zai-org/GLM-5.x 抽取结果为空,请选择其他模型。密钥:RUNCRATE_API_KEY |
| Ollama(本地) | gpt-oss:20b、qwen3:8b,以及 ollama pull 拉取的任意模型 |
✅ | ✅ | 本地运行时,在 http://localhost:11434/v1 提供 OpenAI 兼容子集,包含 /v1/embeddings,一个端点即可覆盖 LLM 与嵌入器(embeddinggemma)。接口形式上必填密钥,但其值会被忽略。密钥:OLLAMA_API_KEY(仅 Ollama Cloud 需要) |
| Cerebras | qwen-3.8-27b、gpt-oss-120b(共享推理);kimi-k2.7-code、gemma-4-31b(独占推理) |
✅ | ✅ | OpenAI 兼容推理接口,所有模型的 tool_choice 均支持 none/auto/required 或指定函数。仅 LLM —— 无嵌入 API(请搭配 OpenAI 兼容嵌入器)。密钥:CEREBRAS_API_KEY |
| Mistral AI | mistral-large-latest、mistral-small-latest、mistral-large-4、ministral-3-8b |
✅ | ✅ | /v1/chat/completions 为 OpenAI 形状,tool_choice 支持 auto/none/any/required 或指定函数。同时提供 /v1/embeddings(mistral-embed,1024 维),一个密钥即可覆盖 LLM 与嵌入器。*-latest 为滚动别名,建议固定带日期的 id。密钥:MISTRAL_API_KEY |
| Moonshot 月之暗面 | kimi-k3.1-pro、kimi-k3.1-pro-highspeed、kimi-k3、kimi-k2.7-code |
✅ | ✅ | OpenAI 兼容聊天接口,tool_choice 支持指定函数。模型 id 不带厂商前缀。仅 LLM —— 无嵌入 API(请搭配 OpenAI 兼容嵌入器)。密钥:MOONSHOT_API_KEY |
| CloudGPU | deepseek-v4.1-flash |
✅ | ✅ | OpenAI 兼容 LLM 预设,模型 id 不带厂商前缀,嵌入模型需单独配置。密钥:CLOUDGPU_API_KEY。配置指南 |
| llm.buzz | openai/gpt-5.4-mini |
✅ | ✅ | OpenAI 兼容网关,模型 id 带厂商前缀(列表:GET https://api.llm.buzz/api/v1/models)。此预设仅 LLM(请搭配 OpenAI 兼容嵌入器)。密钥:LLM_BUZZ_API_KEY |
| LLMTR | qwen/qwen3.8-27b-free、llmtr/qwen3-8-27b |
✅ | ✅ | OpenAI 兼容网关。默认模型为免费的 qwen/qwen3.8-27b-free。llmtr/... 的 llmtr/ 前缀属于模型 id(用 llmtr:llmtr/qwen3-8-27b 覆盖)。同时提供嵌入(llmtr/embeddingmagibu-200m),一个密钥即可覆盖 LLM 与嵌入器。密钥:LLMTR_API_KEY |
| 阿里云百炼 | qwen-plus / qwen-turbo / qwen3.6-plus / deepseek-r1 | ✅ | ✅ | 直接使用,无需修改 |
| 阿里云百炼 | qwen-max / deepseek-v3 | ❌ | ❌ | 仅支持 json_object,不兼容 function calling 结构化输出 |
百炼用户注意:qwen-max 和 deepseek-v3 仅支持
json_object,无法用于 Hyper-Extract 的 function calling 结构化输出。若遇到messages must contain the word 'json'错误或不返回 JSON,请切换到 qwen-plus、qwen-turbo 或 deepseek-r1。详见 Issue #24。
本地部署¶
| 服务 | 模型 | 量化方式 | 显存占用 | 验证状态 |
|---|---|---|---|---|
| LLM | Qwen3.5-9B | GPTQ-Marlin 4bit | ~8GB | ✅ AutoList / AutoGraph |
| Embedding | BAAI/bge-m3 | 无 | ~2GB | ✅ 语义搜索 |
云端 Embedding¶
| 平台 | 模型 | 维度 | 验证状态 |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 1536 | ✅ |
| 阿里云百炼 | text-embedding-v4 | 1024 | ✅ |
分平台快速启动¶
from hyperextract import create_client
# OpenAI
llm, emb = create_client("openai", api_key="sk-xxx")
# 百炼
llm, emb = create_client("bailian", api_key="sk-xxx")
# Anthropic (Claude) —— 仅 LLM;Anthropic 无嵌入接口,请搭配 OpenAI 兼容嵌入器。
# 密钥:LLM 用 ANTHROPIC_API_KEY(或 CLAUDE_API_KEY),嵌入用 OPENAI_API_KEY。
llm, emb = create_client(
llm="anthropic", # 默认模型:claude-opus-4-8(用 "anthropic:<model>" 覆盖)
embedder="openai:text-embedding-3-small",
)
# Google Gemini —— 原生 ChatGoogleGenerativeAI(不是 OrcaRouter 的 gemini/... 网关)。
# 仅 LLM;请搭配 OpenAI 兼容嵌入器。
# 密钥:GOOGLE_API_KEY(或 GEMINI_API_KEY)。别名:"gemini"。
# 额外依赖:pip install 'hyperextract[google]'。
llm, emb = create_client(
llm="google", # 默认模型:gemini-3.8-flash(用 "google:<model>" 覆盖)
embedder="openai:text-embedding-3-small",
)
# DeepSeek —— OpenAI 兼容,但无嵌入接口。V4 模型默认开启 "thinking" 模式,
# Hyper-Extract 会自动关闭以保证工具调用(function_calling)结构化抽取可用。
# 密钥:DEEPSEEK_API_KEY。用 "deepseek:deepseek-v4-pro" 覆盖模型。
llm, emb = create_client(
llm="deepseek",
embedder="openai:text-embedding-3-small", # 或 vllm:bge-m3@localhost:8001/v1
)
# OrcaRouter —— OpenAI 兼容网关,用一把密钥路由 150+ 模型(OpenAI、
# Anthropic、Google、DeepSeek、Qwen、MiniMax、xAI)。默认模型
# "orcarouter/auto" 会选合适的上游;可用 "openai:gpt-4o-mini" 或
# "anthropic:claude-haiku-4-5" 等命名空间 id 覆盖。
# 密钥:ORCAROUTER_API_KEY(回退:OPENAI_API_KEY)。
llm, emb = create_client("orcarouter")
# Atlas Cloud —— OpenAI 兼容网关,模型 id 带厂商前缀
# (deepseek-ai/...、moonshotai/...、qwen/...、openai/...、anthropic/...)。
# 仅 LLM —— 请搭配 OpenAI 兼容嵌入器。
# 密钥:ATLASCLOUD_API_KEY。可用 "atlascloud:moonshotai/kimi-k3" 覆盖模型。
llm, emb = create_client(
llm="atlascloud",
embedder="openai:text-embedding-3-small",
)
# Runcrate —— OpenAI 兼容 API,模型 id 带厂商前缀,同时提供嵌入
# 密钥:RUNCRATE_API_KEY。可用 "runcrate:openai/gpt-oss-120b" 覆盖模型。
llm, emb = create_client(
llm="runcrate", # 默认模型:deepseek-ai/DeepSeek-V4.1-Flash
embedder="runcrate", # 默认嵌入器:BAAI/bge-m3
)
# LLMTR —— OpenAI 兼容网关。默认模型为免费的 qwen/qwen3.8-27b-free。
# llmtr/qwen3-8-27b 这类 id 的 llmtr/ 前缀属于模型 id,
# 用 "llmtr:llmtr/qwen3-8-27b" 覆盖。同时提供嵌入,一个密钥覆盖两者。
# 密钥:LLMTR_API_KEY。
llm, emb = create_client(
llm="llmtr", # 默认模型:qwen/qwen3.8-27b-free
embedder="llmtr", # 默认嵌入器:llmtr/embeddingmagibu-200m
)
# 本地 Ollama —— OpenAI 兼容,地址 http://localhost:11434/v1,嵌入共用同一端点
# 本地运行时密钥值会被忽略。可用 "ollama:qwen3:8b" 覆盖模型,模型 tag 中的冒号会完整保留。
llm, emb = create_client(
llm="ollama", # 默认模型:gpt-oss:20b
embedder="ollama", # 默认嵌入器:embeddinggemma
api_key="ollama",
# Cerebras —— OpenAI 兼容推理接口,模型 id 不带厂商前缀
# 无嵌入 API,请搭配 OpenAI 兼容嵌入器。密钥:CEREBRAS_API_KEY
# 可用 "cerebras:gpt-oss-120b" 覆盖模型。
llm, emb = create_client(
llm="cerebras", # 默认模型:qwen-3.8-27b
embedder="openai:text-embedding-3-small",
)
# Mistral AI —— 聊天与嵌入均为 OpenAI 形状,共用一个密钥
# 密钥:MISTRAL_API_KEY。可用 "mistral:mistral-small-latest" 覆盖模型。
llm, emb = create_client(
llm="mistral", # 默认模型:mistral-large-latest
embedder="mistral", # 默认嵌入器:mistral-embed
)
# Moonshot 月之暗面 / Kimi —— OpenAI 兼容聊天接口,模型 id 不带厂商前缀
# 无嵌入 API,请搭配 OpenAI 兼容嵌入器。密钥:MOONSHOT_API_KEY
# 可用 "moonshot:kimi-k3" 覆盖模型。
llm, emb = create_client(
llm="moonshot", # 默认模型:kimi-k3.1-pro
embedder="openai:text-embedding-3-small",
# CloudGPU —— OpenAI 兼容 LLM API,模型 id 不带厂商前缀。
# 不提供嵌入,请单独选择嵌入模型。
# 密钥:CLOUDGPU_API_KEY。可用 "cloudgpu:kimi-k2.6" 覆盖模型。
llm, emb = create_client(
llm="cloudgpu", # 默认模型:deepseek-v4.1-flash
embedder="openai",
)
# 本地 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 配置指南。
vLLM 部署¶
启动 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
启动 Embedding 服务¶
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
使用建议¶
本地 vLLM 部署推荐使用非 Thinking 模型。
本地部署时,Thinking 模型(如 Qwen3.5 thinking 模式)会输出 <think>...</think> 标签,与约束解码要求的从首个 token 开始 JSON 合规冲突。部署 Qwen3.5-9B 时请关闭 thinking 模式:
百炼渠道的 DeepSeek-R1 已验证可用 — 百炼平台在后端过滤了 <think> 标签输出,AutoGraph 和 with_structured_output 均可正常工作。若通过其他渠道接入 DeepSeek-R1,仍可能受 thinking 输出影响。
量化模型推荐 GPTQ-Marlin,AWQ 在 vLLM 0.21.0 中存在兼容性问题。