Instructor 结构化输出

WHENWhen deploying instructor with from_openai (or routes converging on it: OpenAI / OpenRouter / Anyscale / Together / Databricks) to production

ACTIONrun the Python interpreter with the -O optimization flag, because from_openai validates the (provider, mode) pair via Python assert statements that -O strips silently

CONSEQUENCEUnder python -O, the assert mode in {...} blocks in from_openai are removed; invalid (provider, mode) combinations reach the LLM call producing malformed kwargs, undefined provider responses, or silently wrong-shaped completions across 5 OpenAI-family base_urls

WHENWhen pointing instructor at self-hosted OpenAI-compatible endpoints (vLLM / TGI / Ollama / LiteLLM proxy) or providers whose base_url is not in the 16-substring table (azure_openai / google / litellm / ollama)

ACTIONrely on instructor's automatic mode validation, because get_provider() will return Provider.UNKNOWN — neither the from_openai assert blocks nor the raise ModeError branches fire, leaving the (provider, mode) pair entirely unchecked

CONSEQUENCESelf-hosted endpoints fall to Provider.UNKNOWN; assert blocks dispatch on Provider enum values (OPENROUTER/ANYSCALE/TOGETHER/OPENAI/DATABRICKS) so all assertions silently pass, and provider-specific optimizations are skipped — debugging wrong-shaped responses requires reading the dispatch table source

WHENWhen passing max_retries to instructor (especially via from_provider)

ACTIONtreat max_retries as a single semantic — it appears at three independent code points with different defaults: patch.py default=1 (reask only), Instructor.create default=3 (reask only), and auto_client.py:180-185 transparently passes it to openai.OpenAI(max_retries=...) which is the SDK's HTTP-level retry (network only) — a single max_retries=5 to from_provider can yield 5 reasks × 5 SDK HTTP retries = 25 worst-case API calls

CONSEQUENCEPassing one max_retries through from_provider transparently amplifies into both instructor reask and SDK HTTP retry layers, producing up to N×N API calls; on rate-limited or pay-per-call providers this drains the cost budget and triggers vendor throttling cascades within a single user request