一套测试横跨十大 LLM 提供商instructor 核心提供者统一测试套件实战与源码解析【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructortests/llm/test_core_providers/是 instructor 仓库中一套面向OpenAI、Anthropic、GoogleGemini、Cohere、xAI、Mistral、Cerebras、Fireworks、Writer、Perplexity十大提供商的统一测试套件同一份测试代码通过instructor.from_provider()参数化自动在全部可用提供商上运行。本文将完整拆解该套件的组织方式、配置中枢、能力矩阵、运行命令与测试证据解读方法帮助你理解 instructor 如何保证多提供商行为一致并掌握自行扩展测试与接入新提供商的完整流程。为什么需要一套测试跑遍所有提供商instructor 的核心价值是无论底层是 OpenAI 的工具调用Tools、Anthropic 的 AnthropicTools还是 Perplexity 的 JSON 模式上层都呈现统一的client.create(response_model...)结构化输出 API。这带来的直接挑战是如何验证同一份结构化输出能力在十家提供商上行为一致传统做法是为每家提供商复制一份测试结果就是 README 中描述的困境重复代码、维护成本高、新提供商接入时需要复制粘贴整份测试。该套件的设计哲学见 tests/llm/test_core_providers/README.md是Instead of duplicating the same tests for each provider, we useinstructor.from_provider()with parameterization to run the same test suite against all providers simultaneously.即不复制测试用参数化一次运行。测试代码只写一份pytest通过pytest_generate_tests钩子为每个可用提供商生成一份参数化用例测试函数通过provider_configfixture 拿到(model, mode)二元组再调用instructor.from_provider(model, modemode)构建客户端。测试组织六个核心测试文件套件把跨提供商必须一致的能力拆成六个测试文件全部位于 tests/llm/test_core_providers/测试文件覆盖范围test_basic_extraction.py简单对象提取、列表提取、嵌套模型、PydanticField描述test_streaming.py部分流式Partial、可迭代流式Iterable、联合类型流式test_validation.py字段校验器、ge/le约束、自定义校验、max_retriestest_retries.py重试逻辑与max_retries参数test_response_modes.py不同客户端方法create、chat.completions.create、messages.create、create_with_completiontest_simple_types.py简单类型int、bool、str、Literal、Union、Enum、Annotated[int, Field(...)]每个文件内的测试都遵循同一套模板以 test_basic_extraction.py 为例pytest.mark.asyncio async def test_simple_extraction(provider_config): Test simple single object extraction. model, mode provider_config client instructor.from_provider(model, modemode, async_clientTrue) user await client.create( response_modelUser, messages[{role: user, content: Extract: Jason is 25 years old}], ) assert isinstance(user, User) assert user.name Jason assert user.age 25注意几个关键点全部是异步测试统一使用async_clientTrue确保只测一套异步接口路径断言是纯 Pydantic 级别的isinstance 字段值断言不涉及任何提供商私有类型从而天然可移植响应模型即测试契约User、UserList、UserWithAddress等模型直接定义在测试文件内说明该测试只关注结构化输出契约本身。test_streaming.py额外展示了 instructor DSL 的跨提供商验证Partial[User]部分流式逐块返回模型的部分填充实例、Iterable[User]可迭代流式逐个返回完整对象、以及Iterable[Union[Weather, SearchQuery]]联合类型流式后者依赖 capabilities.py 中的union_streaming能力标记来跳过不支持的提供商。配置中枢tests/llm/shared_config.py 深度解析套件的心脏是 tests/llm/shared_config.py它定义了三件事提供商清单、可用性探测、自动参数化。PROVIDER_CONFIGS四元组清单每个提供商用一个四元组描述PROVIDER_CONFIGS [ (openai/gpt-4.1-mini, instructor.Mode.TOOLS, OPENAI_API_KEY, openai), (anthropic/claude-haiku-4-5-20251001, instructor.Mode.ANTHROPIC_TOOLS, ANTHROPIC_API_KEY, anthropic), (GOOGLE_GENAI_MODEL, instructor.Mode.GENAI_STRUCTURED_OUTPUTS, GOOGLE_API_KEY, google.genai), (cohere/command-a-03-2025, instructor.Mode.COHERE_TOOLS, COHERE_API_KEY, cohere), (xai/grok-3-mini, instructor.Mode.XAI_TOOLS, XAI_API_KEY, xai_sdk), (mistral/ministral-8b-latest, instructor.Mode.MISTRAL_TOOLS, MISTRAL_API_KEY, mistralai), (cerebras/llama3.1-70b, instructor.Mode.CEREBRAS_TOOLS, CEREBRAS_API_KEY, cerebras), (fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct, instructor.Mode.FIREWORKS_TOOLS, FIREWORKS_API_KEY, fireworks), (writer/palmyra-x5, instructor.Mode.WRITER_TOOLS, WRITER_API_KEY, writerai), (perplexity/sonar-pro, instructor.Mode.PERPLEXITY_JSON, PERPLEXITY_API_KEY, openai), ]每个元组的四个元素含义依次是模型字符串provider/model-name格式/前即提供商名同时用于生成测试 ID 和识别能力instructor 模式必须与提供商客户端的调用方式匹配。例如 OpenAI 走instructor.Mode.TOOLSAnthropic 走instructor.Mode.ANTHROPIC_TOOLSPerplexity 走instructor.Mode.PERPLEXITY_JSON——README 特别强调Pick the mode that matches the providers client必需的 API Key 环境变量如OPENAI_API_KEY必需的 Python 包名如openai、google.genai、xai_sdk、writerai。两个值得注意的细节Google 的模型字符串从环境变量读取GOOGLE_GENAI_MODEL os.getenv(GOOGLE_GENAI_MODEL, )默认空字符串即未配置 Google 模型则不跑 Google 用例Perplexity 复用openai包因为它走 OpenAI 兼容 API 传输注释明确写着Perplexity transports over OpenAI-compatible API这也印证了 instructor 统一接口的设计——传输层兼容的提供商可以共享 SDK 依赖。get_available_providers双条件可用性探测def get_available_providers() - list[tuple[str, instructor.Mode]]: available [] for model, mode, env_var, package in PROVIDER_CONFIGS: if not model: continue if not os.getenv(env_var): continue try: parts package.split(.) if len(parts) 1: __import__(parts[0]) __import__(package) # 例如 google.genai 需连父包一起导入 else: __import__(package) available.append((model, mode)) except ImportError: continue return available一个提供商要进入测试矩阵必须同时满足两个条件对应的 API Key 环境变量已设置os.getenv(env_var)非空对应的 SDK 包可导入__import__(package)不抛ImportError。任一条不满足即静默跳过。这就是 README 所说Tests automatically skip if the API key or package is not available的底层实现。对嵌套包如google.genai会先导入父包再导入完整包避免部分安装导致误判。pytest_generate_tests零样板参数化def pytest_generate_tests(metafunc): if provider_config in metafunc.fixturenames: available get_available_providers() if not available: pytest.skip(No providers available (missing API keys or packages)) ids [model.split(/)[0] for model, _ in available] metafunc.parametrize(provider_config, available, idsids)这是整个套件的魔法所在任何测试函数只要声明provider_config参数pytest 就会自动为每个可用提供商生成一条用例测试 ID 取模型字符串/前的提供商名如openai、anthropic、google。如果没有任何可用提供商整个文件直接跳过。conftest.py 只是把pytest_generate_tests和pytest_configure从 shared_config 中导入让核心测试目录自动生效。pytest_configure还注册了 10 个提供商专属 markeropenai、anthropic、google等供需要定向标记/筛选的测试使用。同时 shared_config 提供skip_if_provider_unavailable(provider_name)便捷函数用于在按提供商定向运行场景下手动跳过。能力矩阵capabilities.py 按能力跳过不同提供商的能力并不完全对齐例如 Gemini 不支持 Union 类型和 Enum 类型只支持OptionalPerplexity 的流式支持有限。如果强行让所有提供商跑所有测试会得到大量无意义的失败。解决方案是 capabilities.py 中的能力矩阵Capability Literal[ streaming, partial_streaming, iterable_streaming, list_extraction, nested_models, validation, response_model_none, create_with_completion, union_types, enum_types, union_streaming, ] PROVIDER_CAPABILITIES: dict[str, set[Capability]] { google: { streaming, partial_streaming, iterable_streaming, list_extraction, nested_models, validation, response_model_none, create_with_completion, # Note: Gemini doesnt support Union types or Enum types, only Optional }, perplexity: { # Limited streaming support list_extraction, nested_models, validation, create_with_completion, }, ... }测试中通过skip_if_unsupported(provider_config, capability)在运行时检查并跳过。例如 test_simple_types.py 中async def test_union(provider_config): skip_if_unsupported(provider_config, union_types) ...其实现逻辑为从模型字符串提取提供商名get_provider_nameopenai/gpt-4→openai查能力集合若不在集合中则pytest.skip并给出带模型与模式的明确原因。这套机制保证了能力边界是显式声明、集中管理的新增能力或调整边界只需改一张表。运行核心提供者测试命令全集套件依赖uvAstral 的快速 Python 包管理器运行命令均以仓库根目录为基准运行全部核心提供者测试uv run pytest tests/llm/test_core_providers/ -v运行单个测试文件uv run pytest tests/llm/test_core_providers/test_basic_extraction.py -v运行单个测试用例uv run pytest tests/llm/test_core_providers/test_basic_extraction.py::test_simple_extraction -v只跑某个提供商利用-k按测试 ID 过滤ID 即提供商名# 只跑 OpenAI uv run pytest tests/llm/test_core_providers/ -k openai -v # 只跑 Anthropic uv run pytest tests/llm/test_core_providers/ -k anthropic -v # 只跑 Google uv run pytest tests/llm/test_core_providers/ -k google -v需要的 API Key测试会在 API Key 或依赖包缺失时自动跳过因此设置多少就测多少环境变量对应提供商说明OPENAI_API_KEYOpenAI默认模型openai/gpt-4.1-miniANTHROPIC_API_KEYAnthropic默认模型anthropic/claude-haiku-4-5-20251001GOOGLE_API_KEYGoogleGemini需同时设置GOOGLE_GENAI_MODEL指定模型字符串如google/gemini-3-flashCOHERE_API_KEYCohere默认模型cohere/command-a-03-2025XAI_API_KEYxAIGrok默认模型xai/grok-3-miniMISTRAL_API_KEYMistral默认模型mistral/ministral-8b-latestCEREBRAS_API_KEYCerebras默认模型cerebras/llama3.1-70bFIREWORKS_API_KEYFireworks默认模型fireworks/accounts/fireworks/models/llama-v3p3-70b-instructWRITER_API_KEYWriter默认模型writer/palmyra-x5PERPLEXITY_API_KEYPerplexity默认模型perplexity/sonar-pro复用openaiSDK模型名、模式、SDK 要求与凭据检查的权威来源始终是 tests/llm/shared_config.py 中的PROVIDER_CONFIGS如模型升级换代直接修改该文件即可。如何解读测试证据从 ProviderSpec 到 JUnit 报告README 用一整节专门讲Interpreting test evidence因为这套套件经常作为 CI 证据源而证据的解读有严格边界。ProviderSpec模式的唯一权威声明instructor/v2/core/provider_specs.py 中ProviderSpec声明了每个提供商的规范化模式normalized modes、别名aliases与显式拒绝的模式unsupported modes。它解决了同一模式在不同提供商处的名字不同的归一化问题。README 的告诫是Neither a registry entry nor a green job certifies a provider/API/mode combination that was not exercised.即注册表条目或通过的 CI 任务都不能为未被实际执行过的提供商/API/模式组合背书。一个提供商在注册表里存在、甚至 CI 显示绿色都不代表它所有模式都被真实跑过。JUnit 报告语义scripts/provider_test_evidence.pyCI 工作流使用 scripts/provider_test_evidence.py 汇总 JUnit 报告其 docstring 明确写着Summarize pytest JUnit evidence without inferring live provider certification。该脚本的核心语义约束缺失凭据/配置且零收集用例非失败但属于显式未测试缺失或不可读的报告计数未知脚本对无法解析的 XML 输出No usable JUnit report; execution and counts are unknown.空报告意味着零结果全跳过all-skipped的运行不构成通过证据初始、重试与文档化模型报告保持分离一次成功的重试不会抹掉最初的失败计数是 JUnit 的 outcome 数不是 API 调用次数也不是跨尝试的独立测试数跳过类别是粗粒度标签精确原因要看pytest -rs日志。脚本会把跳过归类为credentials unavailableAPI key 相关、unsupported by test capability policy能力矩阵拒绝、SDK/package unavailable依赖缺失等配置存在性的报告不含密钥值收集或选择阶段被省略的测试无法从 XML 推断从未启动的任务无法产出汇总。哪些测试不算活体提供商证据README 明确划定了证据边界test_retries.py 只接受重试设置而不强制制造失败尝试max_retries3只是传参验证test_response_modes.py 检查非空补全completion is not None本地 Responses SDK 契约测试tests/v2/test_responses_sdk_contract.py用 loopback HTTP 单独校验同步/异步线路映射、SDK 响应类型与 HTTP 错误原因属于本地契约测试而非活体提供商证据单元/处理器测试使用测试替身test doubles同样不构成活体提供商证据关键提醒marker 选择-k过滤不是网络沙箱因此离线覆盖率运行时不要携带提供商凭据。添加新核心测试与接入新提供商添加新核心测试五步在tests/llm/test_core_providers/下新建测试文件测试函数签名使用provider_config参数解包model, mode provider_config用instructor.from_provider(model, modemode)创建客户端只写提供商无关的断言纯 Pydantic 模型与字段值。若新测试依赖某能力先在capabilities.py中声明能力并调用skip_if_unsupported保持能力边界显式。接入新提供商四步在 tests/llm/shared_config.py 的PROVIDER_CONFIGS增加一个四元组(provider/model-name, instructor.Mode.PROVIDER_SPECIFIC_MODE, API_KEY_ENV_VAR, package.name)选择与该提供商客户端匹配的模式参考instructor.Mode或对应提供商指南如 docs/integrations/index.md若该提供商有模式别名或能力差异同步在capabilities.py登记能力集合设置 API Key 后测试会自动对该提供商运行——零测试代码改动。这就是 README 强调的收益闭环新增提供商的成本收敛到一个配置元组 一张能力表。收益与迁移现状README 给出的收益清单均已由源码结构印证更少代码消除了约 3,500 行重复测试代码更易维护测试逻辑只改一处自动作用于所有提供商共享覆盖同一套断言应用于所有已配置的提供商用例更快迭代新提供商只需改一个配置文件行为一致尽早捕获提供商特有的怪癖如 Gemini 不支持 Union。迁移状态方面仓库已完成共享配置建立、六个核心测试文件就位、工具方法统一为provider/model格式、清理了提供商专属重复测试删除 cerebras/fireworks/perplexity/cohere/xai/mistral 六个整个提供商目录以及其余提供商下 35 个重复测试文件。当前 10 家提供商的能力覆盖情况可直接对照 capabilities.py 中的PROVIDER_CAPABILITIES矩阵查阅。小结tests/llm/test_core_providers/是理解 instructor 多提供商架构的最佳入口shared_config.py提供参数化引擎与提供商清单capabilities.py显式管理能力边界六个测试文件以纯 Pydantic 契约覆盖提取、流式、校验、重试、响应模式与简单类型而scripts/provider_test_evidence.py定义了严格的证据解读纪律。对使用者而言它既是十家提供商行为一致性的可执行证明也是接入新提供商时几乎零成本的模板——一条四元组配置即可让新提供商享受全部核心测试覆盖。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 一套测试横跨十大 LLM 提供商：instructor 核心提供者统一测试套件实战与源码解析
一套测试横跨十大 LLM 提供商instructor 核心提供者统一测试套件实战与源码解析【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructortests/llm/test_core_providers/是 instructor 仓库中一套面向OpenAI、Anthropic、GoogleGemini、Cohere、xAI、Mistral、Cerebras、Fireworks、Writer、Perplexity十大提供商的统一测试套件同一份测试代码通过instructor.from_provider()参数化自动在全部可用提供商上运行。本文将完整拆解该套件的组织方式、配置中枢、能力矩阵、运行命令与测试证据解读方法帮助你理解 instructor 如何保证多提供商行为一致并掌握自行扩展测试与接入新提供商的完整流程。为什么需要一套测试跑遍所有提供商instructor 的核心价值是无论底层是 OpenAI 的工具调用Tools、Anthropic 的 AnthropicTools还是 Perplexity 的 JSON 模式上层都呈现统一的client.create(response_model...)结构化输出 API。这带来的直接挑战是如何验证同一份结构化输出能力在十家提供商上行为一致传统做法是为每家提供商复制一份测试结果就是 README 中描述的困境重复代码、维护成本高、新提供商接入时需要复制粘贴整份测试。该套件的设计哲学见 tests/llm/test_core_providers/README.md是Instead of duplicating the same tests for each provider, we useinstructor.from_provider()with parameterization to run the same test suite against all providers simultaneously.即不复制测试用参数化一次运行。测试代码只写一份pytest通过pytest_generate_tests钩子为每个可用提供商生成一份参数化用例测试函数通过provider_configfixture 拿到(model, mode)二元组再调用instructor.from_provider(model, modemode)构建客户端。测试组织六个核心测试文件套件把跨提供商必须一致的能力拆成六个测试文件全部位于 tests/llm/test_core_providers/测试文件覆盖范围test_basic_extraction.py简单对象提取、列表提取、嵌套模型、PydanticField描述test_streaming.py部分流式Partial、可迭代流式Iterable、联合类型流式test_validation.py字段校验器、ge/le约束、自定义校验、max_retriestest_retries.py重试逻辑与max_retries参数test_response_modes.py不同客户端方法create、chat.completions.create、messages.create、create_with_completiontest_simple_types.py简单类型int、bool、str、Literal、Union、Enum、Annotated[int, Field(...)]每个文件内的测试都遵循同一套模板以 test_basic_extraction.py 为例pytest.mark.asyncio async def test_simple_extraction(provider_config): Test simple single object extraction. model, mode provider_config client instructor.from_provider(model, modemode, async_clientTrue) user await client.create( response_modelUser, messages[{role: user, content: Extract: Jason is 25 years old}], ) assert isinstance(user, User) assert user.name Jason assert user.age 25注意几个关键点全部是异步测试统一使用async_clientTrue确保只测一套异步接口路径断言是纯 Pydantic 级别的isinstance 字段值断言不涉及任何提供商私有类型从而天然可移植响应模型即测试契约User、UserList、UserWithAddress等模型直接定义在测试文件内说明该测试只关注结构化输出契约本身。test_streaming.py额外展示了 instructor DSL 的跨提供商验证Partial[User]部分流式逐块返回模型的部分填充实例、Iterable[User]可迭代流式逐个返回完整对象、以及Iterable[Union[Weather, SearchQuery]]联合类型流式后者依赖 capabilities.py 中的union_streaming能力标记来跳过不支持的提供商。配置中枢tests/llm/shared_config.py 深度解析套件的心脏是 tests/llm/shared_config.py它定义了三件事提供商清单、可用性探测、自动参数化。PROVIDER_CONFIGS四元组清单每个提供商用一个四元组描述PROVIDER_CONFIGS [ (openai/gpt-4.1-mini, instructor.Mode.TOOLS, OPENAI_API_KEY, openai), (anthropic/claude-haiku-4-5-20251001, instructor.Mode.ANTHROPIC_TOOLS, ANTHROPIC_API_KEY, anthropic), (GOOGLE_GENAI_MODEL, instructor.Mode.GENAI_STRUCTURED_OUTPUTS, GOOGLE_API_KEY, google.genai), (cohere/command-a-03-2025, instructor.Mode.COHERE_TOOLS, COHERE_API_KEY, cohere), (xai/grok-3-mini, instructor.Mode.XAI_TOOLS, XAI_API_KEY, xai_sdk), (mistral/ministral-8b-latest, instructor.Mode.MISTRAL_TOOLS, MISTRAL_API_KEY, mistralai), (cerebras/llama3.1-70b, instructor.Mode.CEREBRAS_TOOLS, CEREBRAS_API_KEY, cerebras), (fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct, instructor.Mode.FIREWORKS_TOOLS, FIREWORKS_API_KEY, fireworks), (writer/palmyra-x5, instructor.Mode.WRITER_TOOLS, WRITER_API_KEY, writerai), (perplexity/sonar-pro, instructor.Mode.PERPLEXITY_JSON, PERPLEXITY_API_KEY, openai), ]每个元组的四个元素含义依次是模型字符串provider/model-name格式/前即提供商名同时用于生成测试 ID 和识别能力instructor 模式必须与提供商客户端的调用方式匹配。例如 OpenAI 走instructor.Mode.TOOLSAnthropic 走instructor.Mode.ANTHROPIC_TOOLSPerplexity 走instructor.Mode.PERPLEXITY_JSON——README 特别强调Pick the mode that matches the providers client必需的 API Key 环境变量如OPENAI_API_KEY必需的 Python 包名如openai、google.genai、xai_sdk、writerai。两个值得注意的细节Google 的模型字符串从环境变量读取GOOGLE_GENAI_MODEL os.getenv(GOOGLE_GENAI_MODEL, )默认空字符串即未配置 Google 模型则不跑 Google 用例Perplexity 复用openai包因为它走 OpenAI 兼容 API 传输注释明确写着Perplexity transports over OpenAI-compatible API这也印证了 instructor 统一接口的设计——传输层兼容的提供商可以共享 SDK 依赖。get_available_providers双条件可用性探测def get_available_providers() - list[tuple[str, instructor.Mode]]: available [] for model, mode, env_var, package in PROVIDER_CONFIGS: if not model: continue if not os.getenv(env_var): continue try: parts package.split(.) if len(parts) 1: __import__(parts[0]) __import__(package) # 例如 google.genai 需连父包一起导入 else: __import__(package) available.append((model, mode)) except ImportError: continue return available一个提供商要进入测试矩阵必须同时满足两个条件对应的 API Key 环境变量已设置os.getenv(env_var)非空对应的 SDK 包可导入__import__(package)不抛ImportError。任一条不满足即静默跳过。这就是 README 所说Tests automatically skip if the API key or package is not available的底层实现。对嵌套包如google.genai会先导入父包再导入完整包避免部分安装导致误判。pytest_generate_tests零样板参数化def pytest_generate_tests(metafunc): if provider_config in metafunc.fixturenames: available get_available_providers() if not available: pytest.skip(No providers available (missing API keys or packages)) ids [model.split(/)[0] for model, _ in available] metafunc.parametrize(provider_config, available, idsids)这是整个套件的魔法所在任何测试函数只要声明provider_config参数pytest 就会自动为每个可用提供商生成一条用例测试 ID 取模型字符串/前的提供商名如openai、anthropic、google。如果没有任何可用提供商整个文件直接跳过。conftest.py 只是把pytest_generate_tests和pytest_configure从 shared_config 中导入让核心测试目录自动生效。pytest_configure还注册了 10 个提供商专属 markeropenai、anthropic、google等供需要定向标记/筛选的测试使用。同时 shared_config 提供skip_if_provider_unavailable(provider_name)便捷函数用于在按提供商定向运行场景下手动跳过。能力矩阵capabilities.py 按能力跳过不同提供商的能力并不完全对齐例如 Gemini 不支持 Union 类型和 Enum 类型只支持OptionalPerplexity 的流式支持有限。如果强行让所有提供商跑所有测试会得到大量无意义的失败。解决方案是 capabilities.py 中的能力矩阵Capability Literal[ streaming, partial_streaming, iterable_streaming, list_extraction, nested_models, validation, response_model_none, create_with_completion, union_types, enum_types, union_streaming, ] PROVIDER_CAPABILITIES: dict[str, set[Capability]] { google: { streaming, partial_streaming, iterable_streaming, list_extraction, nested_models, validation, response_model_none, create_with_completion, # Note: Gemini doesnt support Union types or Enum types, only Optional }, perplexity: { # Limited streaming support list_extraction, nested_models, validation, create_with_completion, }, ... }测试中通过skip_if_unsupported(provider_config, capability)在运行时检查并跳过。例如 test_simple_types.py 中async def test_union(provider_config): skip_if_unsupported(provider_config, union_types) ...其实现逻辑为从模型字符串提取提供商名get_provider_nameopenai/gpt-4→openai查能力集合若不在集合中则pytest.skip并给出带模型与模式的明确原因。这套机制保证了能力边界是显式声明、集中管理的新增能力或调整边界只需改一张表。运行核心提供者测试命令全集套件依赖uvAstral 的快速 Python 包管理器运行命令均以仓库根目录为基准运行全部核心提供者测试uv run pytest tests/llm/test_core_providers/ -v运行单个测试文件uv run pytest tests/llm/test_core_providers/test_basic_extraction.py -v运行单个测试用例uv run pytest tests/llm/test_core_providers/test_basic_extraction.py::test_simple_extraction -v只跑某个提供商利用-k按测试 ID 过滤ID 即提供商名# 只跑 OpenAI uv run pytest tests/llm/test_core_providers/ -k openai -v # 只跑 Anthropic uv run pytest tests/llm/test_core_providers/ -k anthropic -v # 只跑 Google uv run pytest tests/llm/test_core_providers/ -k google -v需要的 API Key测试会在 API Key 或依赖包缺失时自动跳过因此设置多少就测多少环境变量对应提供商说明OPENAI_API_KEYOpenAI默认模型openai/gpt-4.1-miniANTHROPIC_API_KEYAnthropic默认模型anthropic/claude-haiku-4-5-20251001GOOGLE_API_KEYGoogleGemini需同时设置GOOGLE_GENAI_MODEL指定模型字符串如google/gemini-3-flashCOHERE_API_KEYCohere默认模型cohere/command-a-03-2025XAI_API_KEYxAIGrok默认模型xai/grok-3-miniMISTRAL_API_KEYMistral默认模型mistral/ministral-8b-latestCEREBRAS_API_KEYCerebras默认模型cerebras/llama3.1-70bFIREWORKS_API_KEYFireworks默认模型fireworks/accounts/fireworks/models/llama-v3p3-70b-instructWRITER_API_KEYWriter默认模型writer/palmyra-x5PERPLEXITY_API_KEYPerplexity默认模型perplexity/sonar-pro复用openaiSDK模型名、模式、SDK 要求与凭据检查的权威来源始终是 tests/llm/shared_config.py 中的PROVIDER_CONFIGS如模型升级换代直接修改该文件即可。如何解读测试证据从 ProviderSpec 到 JUnit 报告README 用一整节专门讲Interpreting test evidence因为这套套件经常作为 CI 证据源而证据的解读有严格边界。ProviderSpec模式的唯一权威声明instructor/v2/core/provider_specs.py 中ProviderSpec声明了每个提供商的规范化模式normalized modes、别名aliases与显式拒绝的模式unsupported modes。它解决了同一模式在不同提供商处的名字不同的归一化问题。README 的告诫是Neither a registry entry nor a green job certifies a provider/API/mode combination that was not exercised.即注册表条目或通过的 CI 任务都不能为未被实际执行过的提供商/API/模式组合背书。一个提供商在注册表里存在、甚至 CI 显示绿色都不代表它所有模式都被真实跑过。JUnit 报告语义scripts/provider_test_evidence.pyCI 工作流使用 scripts/provider_test_evidence.py 汇总 JUnit 报告其 docstring 明确写着Summarize pytest JUnit evidence without inferring live provider certification。该脚本的核心语义约束缺失凭据/配置且零收集用例非失败但属于显式未测试缺失或不可读的报告计数未知脚本对无法解析的 XML 输出No usable JUnit report; execution and counts are unknown.空报告意味着零结果全跳过all-skipped的运行不构成通过证据初始、重试与文档化模型报告保持分离一次成功的重试不会抹掉最初的失败计数是 JUnit 的 outcome 数不是 API 调用次数也不是跨尝试的独立测试数跳过类别是粗粒度标签精确原因要看pytest -rs日志。脚本会把跳过归类为credentials unavailableAPI key 相关、unsupported by test capability policy能力矩阵拒绝、SDK/package unavailable依赖缺失等配置存在性的报告不含密钥值收集或选择阶段被省略的测试无法从 XML 推断从未启动的任务无法产出汇总。哪些测试不算活体提供商证据README 明确划定了证据边界test_retries.py 只接受重试设置而不强制制造失败尝试max_retries3只是传参验证test_response_modes.py 检查非空补全completion is not None本地 Responses SDK 契约测试tests/v2/test_responses_sdk_contract.py用 loopback HTTP 单独校验同步/异步线路映射、SDK 响应类型与 HTTP 错误原因属于本地契约测试而非活体提供商证据单元/处理器测试使用测试替身test doubles同样不构成活体提供商证据关键提醒marker 选择-k过滤不是网络沙箱因此离线覆盖率运行时不要携带提供商凭据。添加新核心测试与接入新提供商添加新核心测试五步在tests/llm/test_core_providers/下新建测试文件测试函数签名使用provider_config参数解包model, mode provider_config用instructor.from_provider(model, modemode)创建客户端只写提供商无关的断言纯 Pydantic 模型与字段值。若新测试依赖某能力先在capabilities.py中声明能力并调用skip_if_unsupported保持能力边界显式。接入新提供商四步在 tests/llm/shared_config.py 的PROVIDER_CONFIGS增加一个四元组(provider/model-name, instructor.Mode.PROVIDER_SPECIFIC_MODE, API_KEY_ENV_VAR, package.name)选择与该提供商客户端匹配的模式参考instructor.Mode或对应提供商指南如 docs/integrations/index.md若该提供商有模式别名或能力差异同步在capabilities.py登记能力集合设置 API Key 后测试会自动对该提供商运行——零测试代码改动。这就是 README 强调的收益闭环新增提供商的成本收敛到一个配置元组 一张能力表。收益与迁移现状README 给出的收益清单均已由源码结构印证更少代码消除了约 3,500 行重复测试代码更易维护测试逻辑只改一处自动作用于所有提供商共享覆盖同一套断言应用于所有已配置的提供商用例更快迭代新提供商只需改一个配置文件行为一致尽早捕获提供商特有的怪癖如 Gemini 不支持 Union。迁移状态方面仓库已完成共享配置建立、六个核心测试文件就位、工具方法统一为provider/model格式、清理了提供商专属重复测试删除 cerebras/fireworks/perplexity/cohere/xai/mistral 六个整个提供商目录以及其余提供商下 35 个重复测试文件。当前 10 家提供商的能力覆盖情况可直接对照 capabilities.py 中的PROVIDER_CAPABILITIES矩阵查阅。小结tests/llm/test_core_providers/是理解 instructor 多提供商架构的最佳入口shared_config.py提供参数化引擎与提供商清单capabilities.py显式管理能力边界六个测试文件以纯 Pydantic 契约覆盖提取、流式、校验、重试、响应模式与简单类型而scripts/provider_test_evidence.py定义了严格的证据解读纪律。对使用者而言它既是十家提供商行为一致性的可执行证明也是接入新提供商时几乎零成本的模板——一条四元组配置即可让新提供商享受全部核心测试覆盖。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考