Instructor 统一客户端工厂 from_provider一行代码打通所有 LLM 提供商的 Structured Outputs【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorfrom_provider是 Instructor 面向所有 LLM 提供商的统一客户端工厂函数只需传入provider/model-name形式的模型字符串即可获得一个具备结构化输出能力的 Instructor 客户端无需关心各厂商 SDK 的差异。本指南围绕 docs/concepts/from_provider.md 展开结合仓库源码instructor/v2/auto_client.py、instructor/v2/core/provider_specs.py深入讲解其用法、参数、默认模式与底层分发机制读完你可以用同一套代码在 OpenAI、Anthropic、Google、Ollama、OpenRouter 等二十余个提供商之间自由切换。为什么使用 from_provider在 Instructor 中from_provider提供了一致、简洁的客户端创建入口其核心价值在于简单语法一个函数服务所有提供商instructor.from_provider(openai/gpt-4o-mini)即可完成客户端初始化自动配置提供商特有的 SDK 初始化、API Key 读取、默认 base_url 等由内部构建器自动处理一致接口创建出的客户端都遵循同一套create调用约定不同提供商之间的业务代码零改动类型安全完整的 IDE 类型推断支持源码中通过overload声明了同步/异步与模型字符串的多种返回类型组合见 instructor/v2/auto_client.py#L24-L57轻松切换更换提供商只需改一个字符串无需重写任何调用代码。从源码结构看instructor.from_provider是一个惰性导入的兼容导出真正实现在 v2 模块中instructor/init.py 将from_provider映射到instructor.v2.auto_client而 instructor/auto_client.py 仅做重导出。注意V2 预览。from_provider对受支持提供商默认路由到 v2 实现。旧的提供商专属模式已被弃用它们仍可使用但会发出弃用警告并映射到通用模式Mode.TOOLS、Mode.JSON、Mode.JSON_SCHEMA、Mode.MD_JSON。基本用法基本语法为instructor.from_provider(provider/model-name)import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int # Create a client for any provider client instructor.from_provider(openai/gpt-4o-mini) # Or: instructor.from_provider(anthropic/claude-3-5-sonnet) # Or: instructor.from_provider(google/gemini-2.5-flash) # Use the client as usual user client.create( response_modelUser, messages[{role: user, content: Extract: John is 30 years old}], )创建出的客户端行为与instructor.patch(...)增强后的客户端完全一致create会依据response_model自动完成 Schema 生成、请求格式化与响应校验。仓库的跨提供商测试套件正是利用这一特性用同一组测试用例参数化跑通所有提供商见 tests/llm/test_core_providers/README.md。支持的提供商from_provider覆盖了主流云厂商、快速推理服务与本地模型网关从源码中的_PROVIDER_BUILDERS注册表instructor/v2/auto_client.py#L1532-L1556与PROVIDER_SPECSinstructor/v2/core/provider_specs.py可以确认完整的别名清单。云提供商提供商示例模型字符串OpenAIopenai/gpt-4o、openai/gpt-4o-mini、openai/gpt-5.4-miniAnthropicanthropic/claude-3-5-sonnet、anthropic/claude-3-opusGooglegoogle/gemini-2.5-flash、google/gemini-proAzure OpenAIazure_openai/gpt-4oAWS Bedrockbedrock/claude-3-5-sonnetVertex AIvertexai/gemini-pro或使用google/gemini-pro并传vertexaiTrue快速推理提供商Groqgroq/llama-3.1-70bFireworksfireworks/mixtral-8x7bTogethertogether/meta-llama/Llama-3-70bAnyscaleanyscale/meta-llama/Llama-3-70bCerebrascerebras/gpt-oss-120b其他提供商Mistralmistral/mistral-largeCoherecohere/command-r-plusPerplexityperplexity/llama-3.1-sonarDeepSeekdeepseek/deepseek-chatxAIxai/grok-betaOpenRouteropenrouter/meta-llama/llama-3.1-70bOllamaollama/llama3.2本地模型LiteLLMlitellm/gpt-4o元提供商Databricksdatabricks/...通过环境变量DATABRICKS_HOST等配置Writerwriter/palmyra-x5完整的提供商文档见 docs/integrations/index.md。Provider 字符串格式模型字符串遵循provider/model-name格式from_provider在入口处通过model.split(/, 1)拆解为提供商前缀与模型名instructor/v2/auto_client.py#L107-L123# Correct formats openai/gpt-4o anthropic/claude-3-5-sonnet-20241022 google/gemini-2.5-flash # Incorrect formats (will raise errors) gpt-4o # Missing provider prefix openai # Missing model name openai/gpt-4o/mini # Too many slashes注意拆分逻辑仅按第一个/切分openai/gpt-4o/mini会被解析为 provideropenai、modelgpt-4o/mini这并不符合预期应避免在模型名中携带多余的斜杠。拆出的两部分任意为空都会抛出ConfigurationError源码在 instructor/v2/core/errors 中定义注意与旧文档中的instructor.core.exceptions路径不同以源码为准。异步客户端设置async_clientTrue即可创建异步客户端返回类型对应AsyncInstructorimport asyncio import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int async def main() - None: # Create async client async_client instructor.from_provider(openai/gpt-4o-mini, async_clientTrue) # Use with await await async_client.create( response_modelUser, messages[{role: user, content: Extract: Alice is 25}], ) asyncio.run(main())从源码看async_client参数不仅决定返回类型还会被透传到各提供商的构建器例如 OpenAI 分支会选择openai.AsyncOpenAIinstructor/v2/auto_client.py#L232-L255Anthropic 分支会选择anthropic.AsyncAnthropicinstructor/v2/auto_client.py#L564-L574其余提供商同理。高级配置自定义 API Key可直接传入api_key也可依赖环境变量推荐后者避免密钥进入代码仓库import instructor # Pass API key directly client instructor.from_provider(openai/gpt-4o-mini, api_keysk-your-key-here) # Or use environment variables (recommended) # export OPENAI_API_KEYsk-your-key-here client instructor.from_provider(openai/gpt-4o-mini)源码中api_key会先从 kwargs 中弹出并单独透传若未显式提供各构建器会回退读取对应环境变量如 OpenAI 的OPENAI_API_KEY、Mistral 的MISTRAL_API_KEY、Groq 的GROQ_API_KEY缺失时抛出带明确安装/配置指引的ConfigurationError。模式覆盖通过mode参数覆盖某提供商的默认模式import instructor # OpenAI defaults to TOOLS mode, but you can override client instructor.from_provider( openai/gpt-4o-mini, modeinstructor.Mode.JSON # Use JSON mode instead )Mode枚举定义在 instructor/v2/core/mode.py核心模式包括TOOLS工具调用、JSON_SCHEMA原生 Schema 支持、MD_JSON从文本/代码块中提取 JSON、PARALLEL_TOOLS单次响应多个工具调用、RESPONSES_TOOLSOpenAI Responses API。旧提供商专属模式如ANTHROPIC_TOOLS、GEMINI_JSON在 v2 中会映射到通用模式并发出弃用警告映射关系见 docs/concepts/mode-migration.md。缓存启用响应缓存以复用重复请求的结果from instructor.cache import AutoCache import instructor cache AutoCache(maxsize1000) client instructor.from_provider(openai/gpt-4o-mini, cachecache)AutoCache定义于 instructor/cache/init.py。源码中cache会以显式参数的身份被注入kwargs随后自动流向所有提供商实现instructor/v2/auto_client.py#L103-L105因此无需为每个提供商分别处理缓存逻辑。提供商特定选项通过**kwargs透传提供商特定的客户端参数import os import instructor # For OpenAI client instructor.from_provider( openai/gpt-4o-mini, organizationorg-your-org-id, timeout30.0 ) # OpenAI-compatible multi-model gateways (same client pattern via base_url) client instructor.from_provider( openai/gpt-4o-mini, api_keyYOUR_GATEWAY_KEY, base_urlhttps://api.daoxe.com/v1, ) # For Anthropic client instructor.from_provider(anthropic/claude-3-5-sonnet, max_tokens4096) # For Google with Vertex AI google_api_key os.environ.pop(GOOGLE_API_KEY, None) client instructor.from_provider( google/gemini-pro, vertexaiTrue, projectyour-project-id, locationus-central1, ) if google_api_key is not None: os.environ[GOOGLE_API_KEY] google_api_key这些参数并非原样盲目透传以 OpenAI 构建器为例base_url、organization、timeout、max_retries、default_headers、default_query、http_client等会被专门解析后用于构造底层 SDK 客户端其中timeout缺省时保持not_given、max_retries缺省时使用 SDK 的DEFAULT_MAX_RETRIESinstructor/v2/auto_client.py#L202-L230。Anthropic 构建器还会在未显式传入max_tokens时自动补默认值 4096instructor/v2/auto_client.py#L575-L577。Google 分支支持vertexaiTrue、project、location等参数其中vertexai标志会被取出并传给google.genai.Clientinstructor/v2/auto_client.py#L632-L654这就是文档中临时移出GOOGLE_API_KEY再恢复的原因——Vertex 模式下不需要 API Key而是依赖项目凭据。默认模式每个提供商都有推荐的默认模式。从源码的构建器逻辑instructor/v2/auto_client.py与模式归一化测试tests/v2/test_mode_normalization.py可以确认以下行为OpenAIMode.TOOLSAnthropicMode.TOOLSGooglegenaiMode.TOOLSOllama若模型支持工具调用则Mode.TOOLS否则Mode.JSON—— 构建器内置了llama3.1、llama3.2、qwen2.5、command-r等模型名集合通过模型名子串匹配判断是否支持 toolsinstructor/v2/auto_client.py#L1247-L1269PerplexityMode.MD_JSON其 SDK 走 OpenAI 兼容协议仅支持 markdown JSON 模式见 instructor/v2/core/provider_specs.py其他提供商视能力而定多数为Mode.TOOLS部分为Mode.MD_JSON或Mode.JSON_SCHEMA旧的提供商专属模式仍可用但已弃用详细迁移映射见 docs/concepts/mode-migration.md。需要时可用mode参数覆盖这些默认值。错误处理from_provider会对常见问题抛出清晰的异常异常类型ConfigurationError定义于 instructor/v2/core/errorsimport instructor from instructor.v2.core.errors import ConfigurationError try: # Invalid provider format client instructor.from_provider(invalid-format) except ConfigurationError as e: print(fConfiguration error: {e}) Configuration error: Model string must be in format provider/model-name (e.g. openai/gpt-5.4-mini or anthropic/claude-3-sonnet) try: # Unsupported provider client instructor.from_provider(unsupported/provider) except ConfigurationError as e: print(fUnsupported provider: {e}) Unsupported provider: unsupported. Supported providers are: [openai, azure_openai, databricks, anthropic, google, generative-ai, vertexai, mistral, cohere, perplexity, groq, writer, bedrock, cerebras, deepseek, fireworks, ollama, openrouter, xai, litellm] try: # Missing required package client instructor.from_provider(anthropic/claude-3) except ConfigurationError as e: print(fMissing package: {e}) # Install with: pip install anthropic当provider不在_PROVIDER_BUILDERS中时异常信息会附带完整的受支持列表当所需 SDK 未安装时异常信息会给出精确的安装命令如pip install anthropic、pip install openai、pip install google-genai这些提示文案均来自各构建器的except ImportError分支。环境变量绝大多数提供商支持通过环境变量配置无需在代码中硬编码密钥# OpenAI export OPENAI_API_KEYsk-your-key # Anthropic export ANTHROPIC_API_KEYsk-ant-your-key # Google export GOOGLE_API_KEYyour-key # Azure OpenAI export AZURE_OPENAI_API_KEYyour-key export AZURE_OPENAI_ENDPOINThttps://your-resource.openai.azure.com/ # AWS Bedrock export AWS_DEFAULT_REGIONus-east-1 export AWS_ACCESS_KEY_IDyour-key export AWS_SECRET_ACCESS_KEYyour-secret # Others export MISTRAL_API_KEYyour-key export COHERE_API_KEYyour-key export GROQ_API_KEYyour-key export DEEPSEEK_API_KEYyour-key export OPENROUTER_API_KEYyour-key除此之外源码还支持ANYSCALE_API_KEY、TOGETHER_API_KEY、PERPLEXITY_API_KEY、DATABRICKS_HOST/DATABRICKS_TOKEN、GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION等对应各自的构建器。在提供商之间切换from_provider最大的优势之一就是轻松切换提供商import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int # Easy to switch providers PROVIDER openai/gpt-4o-mini # Change this to switch # PROVIDER anthropic/claude-3-5-sonnet # PROVIDER google/gemini-2.5-flash client instructor.from_provider(PROVIDER) # Same code works for all providers user client.create( response_modelUser, messages[{role: user, content: Extract: Bob is 40}], )从仓库测试的用法也可以看到这种一致性被广泛依赖跨提供商测试套件通过参数化model与mode用同一份create调用同时验证所有提供商的结构化提取、重试、流式与校验行为见 tests/llm/test_core_providers/test_basic_extraction.py、tests/llm/test_core_providers/test_retries.py 等。最佳实践使用环境变量将 API Key 存放在环境变量而非代码中既安全又便于多环境切换善用类型提示from_provider对同步/异步、已知模型名返回类型都有overload声明让 IDE 提供自动补全与类型检查处理错误在创建客户端时用try-except包裹捕获ConfigurationError与ImportError按需缓存对高频重复请求使用AutoCache注意命中率与内存上限maxsize选择合适的模式优先使用提供商默认模式仅在确有需要时用mode覆盖。与其他创建方式的对比from_provider vs. 手动 Patching# Old way (still works, but more verbose) import openai import instructor openai_client openai.OpenAI() client instructor.patch(openai_client) # New way (recommended) client instructor.from_provider(openai/gpt-4o-mini)patch仍然可用见 docs/concepts/patching.md适合需要对底层 SDK 客户端做深度自定义的场景from_provider则在快速获得一个能用的 Instructor 客户端上更简洁。from_provider vs. 提供商专属函数各提供商的专属辅助函数from_openai、from_anthropic、from_gemini等在 v2 中已不再作为推荐入口统一改用from_providerimport instructor openai_client instructor.from_provider(openai/gpt-4o-mini) anthropic_client instructor.from_provider(anthropic/claude-3-5-sonnet)从源码结构看这些专属函数仍然保留如 instructor/v2/providers/openai/client.py 中的from_openaifrom_provider内部正是按提供商路由到它们_PROVIDER_BUILDERS注册表instructor/v2/auto_client.py#L1532-L1556就是这层路由关系的集中体现同时 v2 的PROVIDER_SPECSinstructor/v2/core/provider_specs.py统一登记了每个提供商的别名、支持的 Mode、SDK 模块与 from 函数是能力描述的单一事实来源。故障排查提供商未找到如果报不支持的提供商检查提供商名称拼写确认该提供商在受支持列表中检查是否安装了对应的额外依赖包uv pip install instructor[provider-name]。导入错误# Install the required package # For Anthropic uv pip install anthropic # For Google uv pip install google-genai # For others, see integration docs模型字符串非法模型字符串必须是provider/model-name格式# Correct openai/gpt-4o # Incorrect gpt-4o # Missing provider openai # Missing model相关文档快速开始 - 入门指南Patching - Instructor 如何增强底层客户端集成文档 - 各提供商的专属说明模式迁移指南 - 从旧模式迁移到核心模式迁移指南 - 从旧写法迁移安装指南 - 环境与依赖安装【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Instructor 统一客户端工厂 from_provider：一行代码打通所有 LLM 提供商的 Structured Outputs
Instructor 统一客户端工厂 from_provider一行代码打通所有 LLM 提供商的 Structured Outputs【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorfrom_provider是 Instructor 面向所有 LLM 提供商的统一客户端工厂函数只需传入provider/model-name形式的模型字符串即可获得一个具备结构化输出能力的 Instructor 客户端无需关心各厂商 SDK 的差异。本指南围绕 docs/concepts/from_provider.md 展开结合仓库源码instructor/v2/auto_client.py、instructor/v2/core/provider_specs.py深入讲解其用法、参数、默认模式与底层分发机制读完你可以用同一套代码在 OpenAI、Anthropic、Google、Ollama、OpenRouter 等二十余个提供商之间自由切换。为什么使用 from_provider在 Instructor 中from_provider提供了一致、简洁的客户端创建入口其核心价值在于简单语法一个函数服务所有提供商instructor.from_provider(openai/gpt-4o-mini)即可完成客户端初始化自动配置提供商特有的 SDK 初始化、API Key 读取、默认 base_url 等由内部构建器自动处理一致接口创建出的客户端都遵循同一套create调用约定不同提供商之间的业务代码零改动类型安全完整的 IDE 类型推断支持源码中通过overload声明了同步/异步与模型字符串的多种返回类型组合见 instructor/v2/auto_client.py#L24-L57轻松切换更换提供商只需改一个字符串无需重写任何调用代码。从源码结构看instructor.from_provider是一个惰性导入的兼容导出真正实现在 v2 模块中instructor/init.py 将from_provider映射到instructor.v2.auto_client而 instructor/auto_client.py 仅做重导出。注意V2 预览。from_provider对受支持提供商默认路由到 v2 实现。旧的提供商专属模式已被弃用它们仍可使用但会发出弃用警告并映射到通用模式Mode.TOOLS、Mode.JSON、Mode.JSON_SCHEMA、Mode.MD_JSON。基本用法基本语法为instructor.from_provider(provider/model-name)import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int # Create a client for any provider client instructor.from_provider(openai/gpt-4o-mini) # Or: instructor.from_provider(anthropic/claude-3-5-sonnet) # Or: instructor.from_provider(google/gemini-2.5-flash) # Use the client as usual user client.create( response_modelUser, messages[{role: user, content: Extract: John is 30 years old}], )创建出的客户端行为与instructor.patch(...)增强后的客户端完全一致create会依据response_model自动完成 Schema 生成、请求格式化与响应校验。仓库的跨提供商测试套件正是利用这一特性用同一组测试用例参数化跑通所有提供商见 tests/llm/test_core_providers/README.md。支持的提供商from_provider覆盖了主流云厂商、快速推理服务与本地模型网关从源码中的_PROVIDER_BUILDERS注册表instructor/v2/auto_client.py#L1532-L1556与PROVIDER_SPECSinstructor/v2/core/provider_specs.py可以确认完整的别名清单。云提供商提供商示例模型字符串OpenAIopenai/gpt-4o、openai/gpt-4o-mini、openai/gpt-5.4-miniAnthropicanthropic/claude-3-5-sonnet、anthropic/claude-3-opusGooglegoogle/gemini-2.5-flash、google/gemini-proAzure OpenAIazure_openai/gpt-4oAWS Bedrockbedrock/claude-3-5-sonnetVertex AIvertexai/gemini-pro或使用google/gemini-pro并传vertexaiTrue快速推理提供商Groqgroq/llama-3.1-70bFireworksfireworks/mixtral-8x7bTogethertogether/meta-llama/Llama-3-70bAnyscaleanyscale/meta-llama/Llama-3-70bCerebrascerebras/gpt-oss-120b其他提供商Mistralmistral/mistral-largeCoherecohere/command-r-plusPerplexityperplexity/llama-3.1-sonarDeepSeekdeepseek/deepseek-chatxAIxai/grok-betaOpenRouteropenrouter/meta-llama/llama-3.1-70bOllamaollama/llama3.2本地模型LiteLLMlitellm/gpt-4o元提供商Databricksdatabricks/...通过环境变量DATABRICKS_HOST等配置Writerwriter/palmyra-x5完整的提供商文档见 docs/integrations/index.md。Provider 字符串格式模型字符串遵循provider/model-name格式from_provider在入口处通过model.split(/, 1)拆解为提供商前缀与模型名instructor/v2/auto_client.py#L107-L123# Correct formats openai/gpt-4o anthropic/claude-3-5-sonnet-20241022 google/gemini-2.5-flash # Incorrect formats (will raise errors) gpt-4o # Missing provider prefix openai # Missing model name openai/gpt-4o/mini # Too many slashes注意拆分逻辑仅按第一个/切分openai/gpt-4o/mini会被解析为 provideropenai、modelgpt-4o/mini这并不符合预期应避免在模型名中携带多余的斜杠。拆出的两部分任意为空都会抛出ConfigurationError源码在 instructor/v2/core/errors 中定义注意与旧文档中的instructor.core.exceptions路径不同以源码为准。异步客户端设置async_clientTrue即可创建异步客户端返回类型对应AsyncInstructorimport asyncio import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int async def main() - None: # Create async client async_client instructor.from_provider(openai/gpt-4o-mini, async_clientTrue) # Use with await await async_client.create( response_modelUser, messages[{role: user, content: Extract: Alice is 25}], ) asyncio.run(main())从源码看async_client参数不仅决定返回类型还会被透传到各提供商的构建器例如 OpenAI 分支会选择openai.AsyncOpenAIinstructor/v2/auto_client.py#L232-L255Anthropic 分支会选择anthropic.AsyncAnthropicinstructor/v2/auto_client.py#L564-L574其余提供商同理。高级配置自定义 API Key可直接传入api_key也可依赖环境变量推荐后者避免密钥进入代码仓库import instructor # Pass API key directly client instructor.from_provider(openai/gpt-4o-mini, api_keysk-your-key-here) # Or use environment variables (recommended) # export OPENAI_API_KEYsk-your-key-here client instructor.from_provider(openai/gpt-4o-mini)源码中api_key会先从 kwargs 中弹出并单独透传若未显式提供各构建器会回退读取对应环境变量如 OpenAI 的OPENAI_API_KEY、Mistral 的MISTRAL_API_KEY、Groq 的GROQ_API_KEY缺失时抛出带明确安装/配置指引的ConfigurationError。模式覆盖通过mode参数覆盖某提供商的默认模式import instructor # OpenAI defaults to TOOLS mode, but you can override client instructor.from_provider( openai/gpt-4o-mini, modeinstructor.Mode.JSON # Use JSON mode instead )Mode枚举定义在 instructor/v2/core/mode.py核心模式包括TOOLS工具调用、JSON_SCHEMA原生 Schema 支持、MD_JSON从文本/代码块中提取 JSON、PARALLEL_TOOLS单次响应多个工具调用、RESPONSES_TOOLSOpenAI Responses API。旧提供商专属模式如ANTHROPIC_TOOLS、GEMINI_JSON在 v2 中会映射到通用模式并发出弃用警告映射关系见 docs/concepts/mode-migration.md。缓存启用响应缓存以复用重复请求的结果from instructor.cache import AutoCache import instructor cache AutoCache(maxsize1000) client instructor.from_provider(openai/gpt-4o-mini, cachecache)AutoCache定义于 instructor/cache/init.py。源码中cache会以显式参数的身份被注入kwargs随后自动流向所有提供商实现instructor/v2/auto_client.py#L103-L105因此无需为每个提供商分别处理缓存逻辑。提供商特定选项通过**kwargs透传提供商特定的客户端参数import os import instructor # For OpenAI client instructor.from_provider( openai/gpt-4o-mini, organizationorg-your-org-id, timeout30.0 ) # OpenAI-compatible multi-model gateways (same client pattern via base_url) client instructor.from_provider( openai/gpt-4o-mini, api_keyYOUR_GATEWAY_KEY, base_urlhttps://api.daoxe.com/v1, ) # For Anthropic client instructor.from_provider(anthropic/claude-3-5-sonnet, max_tokens4096) # For Google with Vertex AI google_api_key os.environ.pop(GOOGLE_API_KEY, None) client instructor.from_provider( google/gemini-pro, vertexaiTrue, projectyour-project-id, locationus-central1, ) if google_api_key is not None: os.environ[GOOGLE_API_KEY] google_api_key这些参数并非原样盲目透传以 OpenAI 构建器为例base_url、organization、timeout、max_retries、default_headers、default_query、http_client等会被专门解析后用于构造底层 SDK 客户端其中timeout缺省时保持not_given、max_retries缺省时使用 SDK 的DEFAULT_MAX_RETRIESinstructor/v2/auto_client.py#L202-L230。Anthropic 构建器还会在未显式传入max_tokens时自动补默认值 4096instructor/v2/auto_client.py#L575-L577。Google 分支支持vertexaiTrue、project、location等参数其中vertexai标志会被取出并传给google.genai.Clientinstructor/v2/auto_client.py#L632-L654这就是文档中临时移出GOOGLE_API_KEY再恢复的原因——Vertex 模式下不需要 API Key而是依赖项目凭据。默认模式每个提供商都有推荐的默认模式。从源码的构建器逻辑instructor/v2/auto_client.py与模式归一化测试tests/v2/test_mode_normalization.py可以确认以下行为OpenAIMode.TOOLSAnthropicMode.TOOLSGooglegenaiMode.TOOLSOllama若模型支持工具调用则Mode.TOOLS否则Mode.JSON—— 构建器内置了llama3.1、llama3.2、qwen2.5、command-r等模型名集合通过模型名子串匹配判断是否支持 toolsinstructor/v2/auto_client.py#L1247-L1269PerplexityMode.MD_JSON其 SDK 走 OpenAI 兼容协议仅支持 markdown JSON 模式见 instructor/v2/core/provider_specs.py其他提供商视能力而定多数为Mode.TOOLS部分为Mode.MD_JSON或Mode.JSON_SCHEMA旧的提供商专属模式仍可用但已弃用详细迁移映射见 docs/concepts/mode-migration.md。需要时可用mode参数覆盖这些默认值。错误处理from_provider会对常见问题抛出清晰的异常异常类型ConfigurationError定义于 instructor/v2/core/errorsimport instructor from instructor.v2.core.errors import ConfigurationError try: # Invalid provider format client instructor.from_provider(invalid-format) except ConfigurationError as e: print(fConfiguration error: {e}) Configuration error: Model string must be in format provider/model-name (e.g. openai/gpt-5.4-mini or anthropic/claude-3-sonnet) try: # Unsupported provider client instructor.from_provider(unsupported/provider) except ConfigurationError as e: print(fUnsupported provider: {e}) Unsupported provider: unsupported. Supported providers are: [openai, azure_openai, databricks, anthropic, google, generative-ai, vertexai, mistral, cohere, perplexity, groq, writer, bedrock, cerebras, deepseek, fireworks, ollama, openrouter, xai, litellm] try: # Missing required package client instructor.from_provider(anthropic/claude-3) except ConfigurationError as e: print(fMissing package: {e}) # Install with: pip install anthropic当provider不在_PROVIDER_BUILDERS中时异常信息会附带完整的受支持列表当所需 SDK 未安装时异常信息会给出精确的安装命令如pip install anthropic、pip install openai、pip install google-genai这些提示文案均来自各构建器的except ImportError分支。环境变量绝大多数提供商支持通过环境变量配置无需在代码中硬编码密钥# OpenAI export OPENAI_API_KEYsk-your-key # Anthropic export ANTHROPIC_API_KEYsk-ant-your-key # Google export GOOGLE_API_KEYyour-key # Azure OpenAI export AZURE_OPENAI_API_KEYyour-key export AZURE_OPENAI_ENDPOINThttps://your-resource.openai.azure.com/ # AWS Bedrock export AWS_DEFAULT_REGIONus-east-1 export AWS_ACCESS_KEY_IDyour-key export AWS_SECRET_ACCESS_KEYyour-secret # Others export MISTRAL_API_KEYyour-key export COHERE_API_KEYyour-key export GROQ_API_KEYyour-key export DEEPSEEK_API_KEYyour-key export OPENROUTER_API_KEYyour-key除此之外源码还支持ANYSCALE_API_KEY、TOGETHER_API_KEY、PERPLEXITY_API_KEY、DATABRICKS_HOST/DATABRICKS_TOKEN、GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION等对应各自的构建器。在提供商之间切换from_provider最大的优势之一就是轻松切换提供商import instructor from pydantic import BaseModel class User(BaseModel): name: str age: int # Easy to switch providers PROVIDER openai/gpt-4o-mini # Change this to switch # PROVIDER anthropic/claude-3-5-sonnet # PROVIDER google/gemini-2.5-flash client instructor.from_provider(PROVIDER) # Same code works for all providers user client.create( response_modelUser, messages[{role: user, content: Extract: Bob is 40}], )从仓库测试的用法也可以看到这种一致性被广泛依赖跨提供商测试套件通过参数化model与mode用同一份create调用同时验证所有提供商的结构化提取、重试、流式与校验行为见 tests/llm/test_core_providers/test_basic_extraction.py、tests/llm/test_core_providers/test_retries.py 等。最佳实践使用环境变量将 API Key 存放在环境变量而非代码中既安全又便于多环境切换善用类型提示from_provider对同步/异步、已知模型名返回类型都有overload声明让 IDE 提供自动补全与类型检查处理错误在创建客户端时用try-except包裹捕获ConfigurationError与ImportError按需缓存对高频重复请求使用AutoCache注意命中率与内存上限maxsize选择合适的模式优先使用提供商默认模式仅在确有需要时用mode覆盖。与其他创建方式的对比from_provider vs. 手动 Patching# Old way (still works, but more verbose) import openai import instructor openai_client openai.OpenAI() client instructor.patch(openai_client) # New way (recommended) client instructor.from_provider(openai/gpt-4o-mini)patch仍然可用见 docs/concepts/patching.md适合需要对底层 SDK 客户端做深度自定义的场景from_provider则在快速获得一个能用的 Instructor 客户端上更简洁。from_provider vs. 提供商专属函数各提供商的专属辅助函数from_openai、from_anthropic、from_gemini等在 v2 中已不再作为推荐入口统一改用from_providerimport instructor openai_client instructor.from_provider(openai/gpt-4o-mini) anthropic_client instructor.from_provider(anthropic/claude-3-5-sonnet)从源码结构看这些专属函数仍然保留如 instructor/v2/providers/openai/client.py 中的from_openaifrom_provider内部正是按提供商路由到它们_PROVIDER_BUILDERS注册表instructor/v2/auto_client.py#L1532-L1556就是这层路由关系的集中体现同时 v2 的PROVIDER_SPECSinstructor/v2/core/provider_specs.py统一登记了每个提供商的别名、支持的 Mode、SDK 模块与 from 函数是能力描述的单一事实来源。故障排查提供商未找到如果报不支持的提供商检查提供商名称拼写确认该提供商在受支持列表中检查是否安装了对应的额外依赖包uv pip install instructor[provider-name]。导入错误# Install the required package # For Anthropic uv pip install anthropic # For Google uv pip install google-genai # For others, see integration docs模型字符串非法模型字符串必须是provider/model-name格式# Correct openai/gpt-4o # Incorrect gpt-4o # Missing provider openai # Missing model相关文档快速开始 - 入门指南Patching - Instructor 如何增强底层客户端集成文档 - 各提供商的专属说明模式迁移指南 - 从旧模式迁移到核心模式迁移指南 - 从旧写法迁移安装指南 - 环境与依赖安装【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
