本文详解 Crawl4AI 0.7.x 版本起引入的 LLMConfig 类用法，涵盖初始化方式、与 LLMExtractionStrategy 的集成规范、常见 Provider 配置示例（如 Groq、Ollama、OpenAI），并指出关键参数映射逻辑与典型错误规避方法。
本文详解 crawl4ai 0.7.x 版本起引入的 `llmconfig` 类用法，涵盖初始化方式、与 `llmextractionstrategy` 的集成规范、常见 provider 配置示例（如 groq、ollama、openai），并指出关键参数映射逻辑与典型错误规避方法。
自 Crawl4AI v0.7.0（2025年12月发布）起，框架对 LLM 集成层进行了重大重构：原分散于策略类中的 provider、api_token、api_base 等参数被统一收口至独立的 LLMConfig 对象中。这一设计不仅提升了配置一致性，也强化了与底层推理代理库（如 LiteLLM）的兼容性——而你遇到的 "LLM Provider NOT provided" 错误，正是因未正确构造 LLMConfig 或未将其传递给策略所致。
✅ 正确初始化 LLMConfig
LLMConfig 是一个轻量级配置容器，必须显式传入 provider 和认证凭证（如 api_token 或 api_key）。其构造逻辑严格遵循 LiteLLM 的模型标识规范：
from crawl4ai import LLMConfig
import os
# ✅ 正确：Groq 模型（注意 provider 字符串格式）
llm_config = LLMConfig(
provider="groq", # ← 必须为 LiteLLM 支持的标准 provider 名（非模型全名）
api_token=os.getenv("GROQ_API_KEY"), # ← Groq 使用 api_token
model="llama-3.1-70b-versatile", # ← 实际调用的模型 ID（可选，但推荐显式指定）
)
# ✅ 正确：Ollama 本地模型（需运行 ollama serve）
llm_config = LLMConfig(
provider="ollama", # ← 固定值 "ollama"
api_base="http://localhost:11434", # ← Ollama 服务地址（默认端口 11434）
model="llama3:8b", # ← 本地已拉取的模型名（通过 `ollama list` 查看）
)
# ✅ 正确：OpenAI 兼容接口（如 Azure OpenAI、Fireworks、DeepSeek）
llm_config = LLMConfig(
provider="openai", # ← 统一使用 "openai"
api_key=os.getenv("OPENAI_API_KEY"),
api_base="https://api.openai.com/v1", # ← 可覆盖为其他兼容端点
model="gpt-4o-mini",
)
⚠️ 关键注意：
provider参数不是模型路径（如"grok/grok-chat"），而是 LiteLLM 定义的标准 provider 名称。"grok/grok-chat"是无效 provider，LiteLLM 无法识别，故报错。Groq 的合法 provider 是"groq"，模型名则单独通过model参数传入。
✅ 集成到 LLMExtractionStrategy
配置好 LLMConfig 后，将其作为唯一 llm_config 参数传入策略，移除所有旧版独立参数（如 api_token, provider, api_base）：
from crawl4ai.extraction_strategy import LLMExtractionStrategy
from pydantic import BaseModel
class Product(BaseModel):
name: str
price: float
description: str
INSTRUCTION_TO_LLM = "提取商品名称、价格和描述，严格按 JSON Schema 输出。"
llm_strategy = LLMExtractionStrategy(
llm_config=llm_config, # ← 唯一必需字段
schema=Product.model_json_schema(), # ← Pydantic Schema（结构化提取必需）
extraction_type="schema", # ← 或 "text"（自由文本）
instruction=INSTRUCTION_TO_LLM,
chunk_token_threshold=1000, # ← 分块阈值（tokens）
apply_chunking=True, # ← 大页面自动分块
input_format="markdown", # ← 输入内容格式（默认即 markdown）
extra_args={"temperature": 0.0, "max_tokens": 800},
)
❌ 常见错误与修复指南
| 错误现象 | 根本原因 | 修复方案 |
|---|---|---|
LLM Provider NOT provided |
provider 值非法（如 "grok/grok-chat"）或缺失 |
查阅 LiteLLM Providers 文档，使用标准名（"groq", "ollama", "openai"） |
AuthenticationError / Invalid API Key
|
api_token 或 api_key 未设置或环境变量为空 |
使用 print(os.getenv("XXX")) 调试；确保变量名与代码一致（如 GROQ_API_KEY） |
Model not found |
model 参数值在对应 provider 下不存在 |
Groq：检查 支持模型列表；Ollama：执行 ollama list 确认模型已拉取 |
| 策略不生效 / 无 LLM 输出 | 未在 CrawlerRunConfig 中启用该策略 |
确保 CrawlerRunConfig(extraction_config=llm_strategy) 或 extraction_config={"strategy": "LLMExtractionStrategy", ...}
|
? 调试建议
启用 LiteLLM 日志以定位底层请求问题：
import litellm litellm.set_verbose = True # 输出完整 HTTP 请求/响应
同时，在 Crawl4AI 中开启详细日志：
import logging logging.basicConfig(level=logging.DEBUG)
✅ 总结
LLMConfig 是 Crawl4AI v0.7+ 的 LLM 配置中枢，其核心原则是：Provider 名标准化、认证与模型解耦、严格遵循 LiteLLM 规范。只要正确设置 provider（如 "groq"）、api_token/api_key、model，并将其注入 LLMExtractionStrategy.llm_config，即可无缝对接各类开源与商业 LLM 服务。切勿复用旧版参数命名或模型路径写法——这是升级后最常踩的“坑”。
