# https://github.com/567-labs/instructor 项目说明书生成时间：2026-05-16 03:25:27 UTC ## 目录 - [Introduction to Instructor](#introduction) - [Getting Started with Instructor](#getting-started) - [Installation and Setup](#installation) - [Project Structure](#project-structure) - [Core Components Architecture](#core-components) - [Response Models and Type Safety](#response-models) - [Validation and Retry Mechanisms](#validation-retries) - [Streaming and Partial Responses](#streaming) - [LLM Provider Support](#providers) - [Unified Provider Interface](#from-provider) ## Introduction to Instructor ### 相关页面相关主题：[Getting Started with Instructor](#getting-started), [Installation and Setup](#installation)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/567-labs/instructor/blob/main/README.md) - [instructor/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/__init__.py) *(referenced but not directly included in context)* - [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) - [examples/caching_prototype/README.md](https://github.com/567-labs/instructor/blob/main/examples/caching_prototype/README.md) - [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) - [examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) - [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md)

# Introduction to Instructor Instructor is an open-source Python library that simplifies structured output extraction from Large Language Models (LLMs). It provides a unified API across multiple LLM providers, enabling developers to define response models using Pydantic and automatically receive validated, typed outputs from AI responses. ## Overview Instructor addresses a common challenge in LLM development: parsing and validating unstructured model outputs into structured data types. Traditional approaches require manual JSON parsing, custom validation logic, and provider-specific code. Instructor streamlines this by: - Integrating directly with existing LLM provider clients - Using Pydantic models for response schema definition - Automatically retrying failed validations - Supporting multiple providers through a unified interface 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Core Concepts ### Response Model Pattern At the heart of Instructor is the `response_model` parameter. Developers define a Pydantic `BaseModel` class that specifies the expected structure of the LLM response: ```python from pydantic import BaseModel class User(BaseModel): name: str age: int user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ### Automatic Retries When validation fails (e.g., the LLM returns invalid data), Instructor automatically retries the request, passing the validation error back to the model for correction: ```python from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int @field_validator('age') def validate_age(cls, v): if v < 0: raise ValueError('Age must be positive') return v # Instructor automatically retries when validation fails user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Supported Providers Instructor provides a unified API that works with multiple LLM providers. The `from_provider()` method creates a configured client for any supported provider. ### Provider Support Matrix | Provider | Client Method | API Key Environment Variable | |----------|---------------|------------------------------| | OpenAI | `instructor.from_provider("openai/...")` | `OPENAI_API_KEY` | | Anthropic | `instructor.from_provider("anthropic/...")` | `ANTHROPIC_API_KEY` | | Google | `instructor.from_provider("google/...")` | `GOOGLE_API_KEY` | | Ollama | `instructor.from_provider("ollama/...")` | N/A (local) | | Groq | `instructor.from_provider("groq/...")` | `GROQ_API_KEY` | ### Supported Models by Provider **OpenAI Models:** - `openai/gpt-4o` - `openai/gpt-4o-mini` - `openai/gpt-4-turbo` **Anthropic Models:** - `anthropic/claude-3-5-sonnet-20241022` - `anthropic/claude-3-opus-20240229` - `anthropic/claude-3-haiku-20240307` **Google Models:** - `google/gemini-2.0-flash-001` - `google/gemini-pro` - `google/gemini-pro-vision` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md), [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ## Installation ### Standard Installation ```bash pip install instructor ``` ### Package Managers ```bash # Using uv uv add instructor # Using poetry poetry add instructor ``` ### API Key Configuration Providers can be configured using environment variables or passed directly: ```python # From environment variables client = instructor.from_provider("openai/gpt-4o") # Direct API key client = instructor.from_provider( "openai/gpt-4o", api_key="sk-..." ) client = instructor.from_provider( "anthropic/claude-3-5-sonnet", api_key="sk-ant-..." ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Advanced Features ### Caching Instructor includes built-in caching mechanisms to reduce API calls and costs for repeated requests. **AutoCache (In-Memory LRU):** ```python from instructor.cache import AutoCache cache = AutoCache(maxsize=100) client = instructor.from_openai(OpenAI(), cache=cache) ``` **DiskCache (Persistent):** ```python from instructor.cache import DiskCache cache = DiskCache(directory=".instructor_cache") client = instructor.from_openai(OpenAI(), cache=cache) ``` **Cache TTL:** ```python client.create( model="gpt-3.5-turbo", messages=messages, response_model=User, cache_ttl=3600, # 1 hour ) ``` **Performance Benefits:** - **156x faster** cache hits compared to API calls - **Identical results** from cache and API - **Persistent storage** across client instances - Cache invalidation based on prompts, models, schemas, and TTL 资料来源：[examples/caching_prototype/README.md](https://github.com/567-labs/instructor/blob/main/examples/caching_prototype/README.md) ### Hooks System Hooks allow developers to attach event handlers for monitoring and debugging LLM interactions. **Available Hook Events:** - Request details (model, prompt) - Input token count - Token usage statistics - Successful responses - Parse errors - Completion errors - Retry attempt notifications **Hook Types:** 1. **On Request Hook**: Triggered before/after API requests 2. **On Response Hook**: Triggered when responses are received 3. **Parse Error Hook**: Handles JSON parsing failures 4. **Completion Error Hook**: Handles API errors 5. **Retry Hook**: Notifies on retry attempts 资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) ### Batch Processing The `BatchProcessor` provides a unified interface for creating batch jobs across providers. **Supported Operations:** ```bash # Create batch from file instructor batch create \ --messages-file messages.jsonl \ --model "openai/gpt-4o-mini" \ --response-model "examples.User" \ --output-file batch_requests.jsonl # Submit batch instructor batch create-from-file \ --file-path batch_requests.jsonl \ --model "openai/gpt-4o-mini" ``` 资料来源：[examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ### Validation with LLM Validators Beyond standard Pydantic validators, Instructor supports `llm_validator` for complex validation scenarios: ```python from typing_extensions import Annotated from pydantic import BeforeValidator from instructor import llm_validator class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ## Architecture ### Provider Organization The library organizes provider implementations in `instructor/providers/` with consistent patterns: ``` providers/ ├── provider_name/ │ ├── __init__.py │ ├── client.py # Provider-specific client factory │ └── utils.py # Provider-specific utilities ``` **Provider Implementation Categories:** | Category | Providers | |----------|-----------| | Full Implementation (client.py + utils.py) | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | | Client Only | genai, groq, vertexai | | Special (utils.py only) | openai | 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ### Workflow Diagram ```mermaid graph TD A[Define Pydantic Model] --> B[Create Instructor Client] B --> C[Call create with response_model] C --> D{Provider Selection} D -->|OpenAI| E[OpenAI Handler] D -->|Anthropic| F[Anthropic Handler] D -->|Google| G[Google Handler] E --> H[Parse Response] F --> H G --> H H --> I{Validation Passed?} I -->|Yes| J[Return Typed Object] I -->|No| K[Retry with Error] K --> C ``` ## Example Applications ### Citation Extraction Instructor powers applications that extract structured citations from documents: ```bash curl -X 'POST' \ 'https://jxnl--rag-citation-fastapi-app.modal.run/extract' \ -H 'Authorization: Bearer ' \ -d '{ "context": "My name is Jason Liu...", "query": "What did the author do in school?" }' ``` **Response Format:** ```json { "body": "In school, the author went to an arts high school.", "spans": [[91, 106]], "citation": ["arts highschool"] } ``` 资料来源：[examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md) ## Comparison: Without vs With Instructor | Aspect | Traditional Approach | With Instructor | |--------|----------------------|-----------------| | API Calls | Multiple calls for function definition | Single call | | Response Parsing | Manual JSON extraction | Automatic | | Validation | Custom error handling | Pydantic validation | | Retries | Manual implementation | Built-in automatic retries | | Provider Changes | Rewrite code | Same API across providers | 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Next Steps - Review the [official documentation](https://instructor-ai.github.io/instructor/) for detailed guides - Explore example implementations in the `examples/` directory - Contribute via GitHub issues and pull requests - Join the Instructor community for support and updates ## License Instructor is released under the MIT License. See [LICENSE](https://github.com/567-labs/instructor/blob/main/LICENSE) for details. --- ## Getting Started with Instructor ### 相关页面相关主题：[Installation and Setup](#installation), [Response Models and Type Safety](#response-models)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/567-labs/instructor/blob/main/README.md) - [scripts/README.md](https://github.com/567-labs/instructor/blob/main/scripts/README.md) - [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) - [examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md) - [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) - [examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md) - [examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) - [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)

# Getting Started with Instructor Instructor is a Python library that simplifies structured data extraction from Large Language Model (LLM) responses. It integrates with multiple LLM providers and uses Pydantic for automatic validation, retry logic, and type safety. With Instructor, developers can define response models and receive fully validated, typed data directly from LLM outputs. 资料来源：[README.md:1-50]() ## Installation Install Instructor using pip or your preferred package manager: ```bash pip install instructor ``` Or with alternative package managers: ```bash uv add instructor poetry add instructor ``` 资料来源：[README.md:51-60]() ## Quick Start The simplest way to use Instructor is with the `from_provider()` factory function: ```python from pydantic import BaseModel import instructor client = instructor.from_provider("openai/gpt-4o-mini") class Product(BaseModel): name: str price: float in_stock: bool product = client.chat.completions.create( response_model=Product, messages=[{"role": "user", "content": "iPhone 15 Pro, $999, available now"}], ) print(product) # Product(name='iPhone 15 Pro', price=999.0, in_stock=True) ``` 资料来源：[README.md:125-150]() ## Supported Providers Instructor works with multiple LLM providers using a unified API. The provider is automatically detected from the model identifier. ### Provider Configuration Table | Provider | Model Identifier | API Key Parameter | |----------|------------------|-------------------| | OpenAI | `openai/gpt-4o-mini`, `openai/gpt-4o` | `api_key` | | Anthropic | `anthropic/claude-3-5-sonnet` | `api_key` | | Google | `google/gemini-pro` | `api_key` | | Ollama (local) | `ollama/llama3.2` | Local only | | Groq | `groq/llama-3.1-8b-instant` | `api_key` | ### Usage Examples by Provider ```python # OpenAI client = instructor.from_provider("openai/gpt-4o") # Anthropic client = instructor.from_provider("anthropic/claude-3-5-sonnet") # Google client = instructor.from_provider("google/gemini-pro") # Ollama (local) client = instructor.from_provider("ollama/llama3.2") # With explicit API keys client = instructor.from_provider("openai/gpt-4o", api_key="sk-...") client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...") ``` 资料来源：[README.md:61-90]() ## Response Models Response models define the expected output structure using Pydantic's `BaseModel`. Instructor automatically parses and validates LLM responses against these models. ### Basic Model Definition ```python from pydantic import BaseModel class User(BaseModel): name: str age: int ``` ### Without Instructor vs With Instructor ```mermaid graph TD A[User Request] --> B[LLM API Call] B --> C{Using Instructor?} C -->|No| D[Raw JSON Response] D --> E[Manual Parsing] E --> F[Manual Validation] F --> G[Handle Errors] C -->|Yes| H[Response Model Defined] H --> I[Automatic Parsing] I --> J[Automatic Validation] J --> K[Validated Output] ``` 资料来源：[README.md:1-40]() ## Validation Instructor provides automatic retry logic when validation fails. Define custom validators using Pydantic's `@field_validator` decorator. ### Automatic Retries ```python from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int @field_validator('age') def validate_age(cls, v): if v < 0: raise ValueError('Age must be positive') return v # Instructor automatically retries when validation fails user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md:35-50]() ### Custom LLM Validation Use `llm_validator` for content-based validation: ```python from typing_extensions import Annotated from pydantic import BeforeValidator from instructor import llm_validator class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] ``` 资料来源：[examples/validators/readme.md:1-50]() ## Hooks System Hooks allow you to intercept and process requests and responses. The hooks system provides visibility into API calls. ### Available Hook Events 1. **Request Hook**: Triggered before sending a request to the LLM 2. **Parse Error Hook**: Triggered when response parsing fails 3. **Multiple Hooks**: Shows how to attach multiple handlers to the same event ### Hook Usage Example ```python # Hooks provide detailed information about each request: # - Request details (model, prompt) # - Approximate input token count # - Token usage statistics # - Successful responses # - Parse errors # - Completion errors # - Retry attempt notifications ``` 资料来源：[examples/hooks/README.md:1-40]() ## Advanced Features ### Citation with Extraction Extract structured data with precise citations from source text: ```python # FastAPI endpoint example response = client.chat.completions.create( response_model=Facts, messages=[...], ) # Returns extracted facts with exact span positions and citations ``` 资料来源：[examples/citation_with_extraction/README.md:1-80]() ### Batch Processing Process multiple requests efficiently using batch APIs: ```bash # Test OpenAI python run_batch_test.py create --model "openai/gpt-4o-mini" # Test Anthropic python run_batch_test.py create --model "anthropic/claude-3-5-sonnet-20241022" ``` **Supported Batch Models Table** | Provider | Models | |----------|--------| | OpenAI | `gpt-4o-mini`, `gpt-4o`, `gpt-4-turbo` | | Anthropic | `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229`, `claude-3-haiku-20240307` | | Google | `gemini-2.0-flash-001`, `gemini-pro`, `gemini-pro-vision` | 资料来源：[examples/batch_api/README.md:1-70]() ### Fine-Tuning and Distillation Generate fine-tuning datasets from Instructor outputs: ```bash # Run the script to generate training data python three_digit_mul.py # Create fine-tuning job instructor jobs create-from-file math_finetunes.jsonl # With validation data instructor jobs create-from-file math_finetunes.jsonl --n-epochs 4 --validation-file math_finetunes_val.jsonl ``` 资料来源：[examples/distilations/readme.md:1-60]() ## Provider Architecture Each provider is organized in its own subdirectory under `providers/`: ``` providers/ ├── provider_name/ │ ├── __init__.py │ ├── client.py # Provider-specific client factory │ └── utils.py # Provider-specific utilities ``` ### Provider Implementation Patterns | Pattern | Providers | |---------|-----------| | Both `client.py` and `utils.py` | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | | Only `client.py` | genai, groq, vertexai | | Only `utils.py` (core) | OpenAI | 资料来源：[instructor/providers/README.md:1-40]() ## Utility Scripts The repository includes maintenance scripts in the `scripts/` directory: | Script | Purpose | |--------|---------| | `make_clean.py` | Cleans markdown files, removes special whitespace characters | | `check_blog_excerpts.py` | Validates blog posts contain `` tags | | `make_sitemap.py` | Generates sitemap with AI-powered content analysis | | `fix_api_calls.py` | Standardizes API call patterns | | `audit_patterns.py` | Audits documentation for outdated patterns | ### Script Usage ```bash # Clean markdown files python scripts/make_clean.py --dry-run # Check blog excerpts python scripts/check_blog_excerpts.py # Generate sitemap python scripts/make_sitemap.py # Audit documentation python scripts/audit_patterns.py --summary ``` 资料来源：[scripts/README.md:1-100]() ## Next Steps - Explore the [examples directory](https://github.com/567-labs/instructor/tree/main/examples) for complete working examples - Review the [validators documentation](examples/validators/readme.md) for advanced validation patterns - Learn about [hooks](examples/hooks/README.md) for request introspection - Set up [batch processing](examples/batch_api/README.md) for large-scale extractions - Consider [fine-tuning](examples/distilations/readme.md) for domain-specific tasks ## Statistics and Community Instructor is trusted by over 100,000 developers and used in production by teams at OpenAI, Google, Microsoft, and AWS. | Metric | Value | |--------|-------| | Monthly Downloads | 3M+ | | GitHub Stars | 10K+ | | Contributors | 1000+ | 资料来源：[README.md:95-110]() --- ## Installation and Setup ### 相关页面相关主题：[Getting Started with Instructor](#getting-started), [LLM Provider Support](#providers)

Relevant Source Files

以下源码文件用于生成本页说明： - [README.md](https://github.com/567-labs/instructor/blob/main/README.md) - [examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md) - [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) - [examples/caching_prototype/README.md](https://github.com/567-labs/instructor/blob/main/examples/caching_prototype/README.md) - [examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md) - [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) - [providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)

# Installation and Setup ## Overview Instructor is a Python library that enables structured outputs from Large Language Models (LLMs) using type validation through Pydantic. It provides a unified API across multiple LLM providers, allowing developers to define response models and receive type-safe, validated responses automatically. 资料来源：[README.md:1-50]() ## System Requirements | Requirement | Specification | |------------|---------------| | Python Version | 3.9 or higher | | Package Manager | pip, uv, or poetry | | Optional Dependencies | OpenAI, Anthropic, Google SDKs based on provider selection | 资料来源：[examples/distilations/readme.md:10-12]() ## Installation Methods ### Using pip The simplest installation method uses pip: ```bash pip install instructor ``` 资料来源：[README.md:60]() ### Using uv For projects using uv as the package manager: ```bash uv add instructor ``` 资料来源：[README.md:64]() ### Using poetry For projects using Poetry for dependency management: ```bash poetry add instructor ``` 资料来源：[README.md:65]() ## Provider Setup Instructor supports multiple LLM providers with a unified interface. The following diagram illustrates the provider architecture: ```mermaid graph TD A[Application Code] --> B[Instructor Client] B --> C{Provider Type} C -->|OpenAI| D[OpenAI Provider] C -->|Anthropic| E[Anthropic Provider] C -->|Google| F[Gemini Provider] C -->|Ollama| G[Ollama Provider] C -->|Groq| H[Groq Provider] C -->|VertexAI| I[VertexAI Provider] D --> J[Provider API] E --> J F --> J G --> J H --> J I --> J ``` 资料来源：[README.md:70-90]() ### Basic Provider Initialization Initialize clients using the `from_provider()` factory function: ```python # OpenAI client = instructor.from_provider("openai/gpt-4o") # Anthropic client = instructor.from_provider("anthropic/claude-3-5-sonnet") # Google client = instructor.from_provider("google/gemini-pro") # Ollama (local) client = instructor.from_provider("ollama/llama3.2") ``` 资料来源：[README.md:70-85]() ### API Key Configuration API keys can be configured in two ways: | Method | Configuration | |--------|---------------| | Environment Variable | Set provider-specific env var (e.g., `OPENAI_API_KEY`) | | Direct Parameter | Pass `api_key` parameter to `from_provider()` | #### Direct API Key Configuration ```python # OpenAI client = instructor.from_provider("openai/gpt-4o", api_key="sk-...") # Anthropic client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...") # Groq client = instructor.from_provider("groq/llama-3.1-8b-instant", api_key="gsk_...") ``` 资料来源：[README.md:85-92]() ## Basic Usage Pattern The fundamental usage pattern involves: 1. Creating an instructor client 2. Defining a Pydantic response model 3. Calling the client with the response model ```python from pydantic import BaseModel class User(BaseModel): name: str age: int client = instructor.from_provider("openai/gpt-4o") user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md:45-55]() ## Provider-Specific Initialization Some providers may require additional setup: ### OpenAI Provider The OpenAI provider is the reference implementation and uses `from_openai()` or `from_provider()`: ```python import instructor import openai client = instructor.from_provider("openai/gpt-4o-mini") ``` 资料来源：[README.md:70-72]() ### Anthropic Provider Requires the `ANTHROPIC_API_KEY` environment variable: ```bash export ANTHROPIC_API_KEY="your-anthropic-api-key" ``` 资料来源：[examples/batch_api/README.md:45-50]() ### Google Provider For Gemini models, ensure the Google SDK is installed and `GOOGLE_API_KEY` is set: ```bash pip install google-generativeai ``` 资料来源：[examples/batch_api/README.md:55-60]() ## Optional Dependencies Depending on your use case, you may need additional dependencies: ### For Caching Features ```python from instructor.cache import AutoCache, DiskCache ``` 资料来源：[examples/caching_prototype/README.md:12-15]() ### For Validation ```python from instructor import llm_validator, patch ``` 资料来源：[examples/validators/readme.md:15-17]() ### For Sitemap Generation (Documentation Scripts) ```bash uv add openai typer rich tenacity pyyaml ``` 资料来源：[scripts/README.md:85-87]() ## Supported Models by Provider | Provider | Models | |----------|--------| | OpenAI | gpt-4o-mini, gpt-4o, gpt-4-turbo | | Anthropic | claude-3-5-sonnet-20241022, claude-3-opus-20240229, claude-3-haiku-20240307 | | Google | gemini-2.0-flash-001, gemini-pro, gemini-pro-vision | | Ollama | llama3.2, and other local models | 资料来源：[examples/batch_api/README.md:25-35]() ## Verification Installation To verify your installation, create a simple test: ```python import instructor from pydantic import BaseModel class TestModel(BaseModel): result: str client = instructor.from_provider("openai/gpt-4o-mini") result = client.chat.completions.create( model="gpt-4o-mini", response_model=TestModel, messages=[{"role": "user", "content": "Say 'Hello, World!'"}], ) print(result.result) # Should print: Hello, World! ``` ## Common Setup Issues | Issue | Solution | |-------|----------| | API key not found | Set the appropriate environment variable or pass `api_key` parameter | | Invalid model format | Use format `provider/model-name`, e.g., `openai/gpt-4o-mini` | | Unsupported provider | Use `openai`, `anthropic`, `google`, `ollama`, or `groq` | 资料来源：[examples/batch_api/README.md:65-75]() ## Next Steps After installation, consider exploring: - **Response Models**: Define Pydantic models for structured outputs - **Validation**: Add custom validators to response models - **Retries**: Instructor automatically retries failed validations - **Hooks**: Add logging and monitoring to requests 资料来源：[README.md:95-115]() ## Provider Architecture Details The providers directory follows a consistent structure: ``` providers/ ├── provider_name/ │ ├── __init__.py │ ├── client.py # Provider-specific client factory │ └── utils.py # Provider-specific utilities ``` Not all providers require both files. Simpler providers like `genai`, `groq`, and `vertexai` use only `client.py`, while more complex ones like `anthropic`, `bedrock`, and `gemini` include both files. 资料来源：[providers/README.md:1-25]() ## Adding New Providers To add support for a new LLM provider: 1. Create a new subdirectory under `providers/` 2. Add an `__init__.py` file 3. Implement the `from_()` factory function 4. Add provider-specific utilities as needed 资料来源：[providers/README.md:27-32]() --- ## Project Structure ### 相关页面相关主题：[Core Components Architecture](#core-components), [LLM Provider Support](#providers)

相关源码文件

以下源码文件用于生成本页说明： - [instructor/core/client.py](https://github.com/567-labs/instructor/blob/main/instructor/core/client.py) - [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) - [instructor/processing/schema.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/schema.py) - [README.md](https://github.com/567-labs/instructor/blob/main/README.md) - [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) - [examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) - [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) - [examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md)

# Project Structure ## Overview Instructor is a Python library that enables structured outputs from Large Language Models (LLMs) using Pydantic models for type validation. The project is organized into a modular architecture that separates core functionality, provider implementations, and example applications. The primary goal of Instructor's project structure is to provide a unified API that works across multiple LLM providers while maintaining clean separation of concerns between client logic, provider-specific implementations, and response processing. 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## High-Level Architecture ```mermaid graph TD A[User Code] --> B[Core Client API] B --> C[Provider Detection] C --> D{Provider Type} D -->|OpenAI| E[OpenAI Utils] D -->|Anthropic| F[Anthropic Client] D -->|Google| G[Gemini Utils] D -->|Other| H[Provider-specific] E --> I[Response Processing] F --> I G --> I H --> I I --> J[Pydantic Validation] J --> K[Typed Response Model] ``` 资料来源：[instructor/core/client.py](https://github.com/567-labs/instructor/blob/main/instructor/core/client.py) ## Directory Structure ``` instructor/ ├── core/ # Core client and base functionality │ ├── client.py # Main client implementation │ └── ... ├── providers/ # Provider-specific implementations │ ├── anthropic/ # Anthropic Claude integration │ ├── bedrock/ # AWS Bedrock integration │ ├── cerebras/ # Cerebras integration │ ├── cohere/ # Cohere integration │ ├── fireworks/ # Fireworks AI integration │ ├── gemini/ # Google Gemini integration │ ├── genai/ # Google Generative AI │ ├── groq/ # Groq integration │ ├── mistral/ # Mistral AI integration │ ├── perplexity/ # Perplexity AI integration │ ├── vertexai/ # Google Vertex AI integration │ ├── writer/ # Writer AI integration │ ├── xai/ # xAI integration │ └── README.md # Provider documentation ├── processing/ # Response processing and validation │ ├── schema.py # Schema handling │ └── ... ├── cli/ # Command-line interface │ └── ... └── ... examples/ ├── batch_api/ # Batch processing examples ├── citation_with_extraction/ # Extraction examples ├── distilations/ # Fine-tuning examples ├── hooks/ # Hook system examples └── validators/ # Validation examples ``` 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ## Core Components ### Core Client Module The core client module (`instructor/core/client.py`) provides the unified API for all LLM providers. It handles: | Component | Purpose | |-----------|---------| | `from_provider()` | Factory function to create provider-specific clients | | `client.create()` | Unified method for structured completions | | `client.create_partial()` | Streaming partial responses | | `client.create_iterable()` | Iterable response handling | | `client.create_with_completion()` | Responses with completion metadata | 资料来源：[instructor/core/client.py](https://github.com/567-labs/instructor/blob/main/instructor/core/client.py) ### Basic Usage Pattern ```python # Create client from any supported provider client = instructor.from_provider("openai/gpt-4o") # Use unified API for structured outputs user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Provider System ### Provider Organization Each provider follows a consistent directory structure: ``` providers/ ├── provider_name/ │ ├── __init__.py # Module exports │ ├── client.py # Provider-specific client factory (optional) │ └── utils.py # Provider-specific utilities (optional) ``` 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ### Provider Categories | Category | Providers | Files | |----------|-----------|-------| | Full Implementation | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | `client.py` + `utils.py` | | Simplified | genai, groq, vertexai | `client.py` only | | Reference | openai | `utils.py` only (core handles `from_openai()`) | 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ### Supported Providers ```mermaid graph LR A[Instructor] --> B[OpenAI] A --> C[Anthropic] A --> D[Google] A --> E[Groq] A --> F[Vertex AI] A --> G[Mistral] A --> H[ Cohere] A --> I[Fireworks] A --> J[Cerebras] A --> K[Perplexity] A --> L[Writer] A --> M[xAI] ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Processing Module The processing module (`instructor/processing/`) handles response parsing and validation: | Component | Purpose | |-----------|---------| | Schema Handler | Transforms Pydantic models into LLM-compatible schemas | | Response Parser | Extracts structured data from LLM responses | | Validation Engine | Validates responses against Pydantic models | 资料来源：[instructor/processing/schema.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/schema.py) ## Example Applications The `examples/` directory contains functional demonstrations: | Example | Purpose | |---------|---------| | `batch_api/` | Batch processing with multiple providers | | `citation_with_extraction/` | Fact extraction with citations | | `distilations/` | Model fine-tuning with Instructor | | `hooks/` | Event hook system for monitoring | | `validators/` | Custom validation with `llm_validator` | 资料来源：[examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ### Batch Processing Architecture ```mermaid graph TD A[User Messages] --> B[BatchProcessor] B --> C[Provider Detection] C --> D{Provider} D -->|OpenAI| E[batch.jsonl] D -->|Anthropic| F[beta.messages.batches] D -->|Google| G[GCS Simulation] E --> H[Batch Submission] F --> H G --> H H --> I[Batch ID Storage] ``` 资料来源：[examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ### Hooks System The hooks system enables monitoring and logging of API operations: ```python # Hook event types - on_request: Triggered before API call - on_response: Triggered after successful response - on_retry: Triggered during retry attempts - on_error: Triggered on validation/parse errors ``` 资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) ### Validation Examples Custom validation is achieved using Pydantic validators: ```python from instructor import llm_validator, patch class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ## CLI Tools The project includes a command-line interface for common operations: ```bash # Batch processing instructor batch create --messages-file messages.jsonl --model "openai/gpt-4o-mini" # Fine-tuning job creation instructor jobs create-from-file math_finetunes.jsonl ``` 资料来源：[examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md) ## Installation and Dependencies The project supports multiple package managers: ```bash # pip pip install instructor # uv uv add instructor # poetry poetry add instructor ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Scripts and Maintenance The `scripts/` directory contains maintenance utilities: | Script | Purpose | |--------|---------| | `make_clean.py` | Clean markdown whitespace and dashes | | `make_sitemap.py` | Generate documentation sitemap | | `fix_api_calls.py` | Standardize API call patterns | | `fix_old_patterns.py` | Update deprecated patterns | | `audit_patterns.py` | Find outdated patterns in docs | 资料来源：[scripts/README.md](https://github.com/567-labs/instructor/blob/main/scripts/README.md) ## Key Design Patterns ### Unified API Pattern Instructor provides a consistent interface across all providers: ```python # Same code works for any provider client = instructor.from_provider("provider/model-name") result = client.chat.completions.create( response_model=YourModel, messages=[...] ) ``` ### Factory Pattern The `from_provider()` factory function creates appropriate clients based on the provider string: ```python client = instructor.from_provider("openai/gpt-4o") client = instructor.from_provider("anthropic/claude-3-5-sonnet") client = instructor.from_provider("google/gemini-pro") ``` ### Validation Pipeline ```mermaid graph LR A[LLM Response] --> B[Parse Tool Call] B --> C[Extract Arguments] C --> D[JSON Deserialization] D --> E[Pydantic Validation] E -->|Success| F[Typed Response] E -->|Failure| G[Retry with Error] G --> A ``` ## Version Compatibility Notes - OpenAI uses a specialized `utils.py` without a `client.py` because `from_openai()` is defined in the core client - This is because OpenAI serves as the reference implementation for the library - OpenAI utilities are still required by core processing logic for standard handling 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) --- ## Core Components Architecture ### 相关页面相关主题：[Project Structure](#project-structure), [Validation and Retry Mechanisms](#validation-retries)

Relevant Source Files

The following source files are referenced for this page: - [instructor/core/client.py](https://github.com/567-labs/instructor/blob/main/instructor/core/client.py) - [instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py) - [instructor/core/retry.py](https://github.com/567-labs/instructor/blob/main/instructor/core/retry.py) - [instructor/process_response.py](https://github.com/567-labs/instructor/blob/main/instructor/process_response.py)

# Core Components Architecture ## Overview The Instructor library is built on a modular architecture that enables structured LLM outputs with automatic validation and retry capabilities. The core components work together to provide a unified API across multiple LLM providers while maintaining extensibility through hooks and a robust retry mechanism. ```mermaid graph TD A[User Code] --> B[Instructor Client] B --> C[Provider Adapter] C --> D[LLM API] D --> E[Response] E --> F[Response Processor] F --> G[Validation] G -->|Success| H[Typed Response] G -->|Failure| I[Retry Logic] I -->|Retry| D I -->|Max Retries| J[Error] F --> K[Hooks System] K -->|On Response| B K -->|On Validation Error| B ``` ## Architecture Components ### 1. Client Module (`instructor/core/client.py`) The client module serves as the primary entry point for the Instructor library. It provides factory functions for creating provider-specific clients and implements the unified API interface. #### Key Responsibilities | Responsibility | Description | |---------------|-------------| | Client Factory | Creates provider-specific clients via `from_provider()` | | API Unification | Provides consistent interface across all LLM providers | | Method Dispatch | Routes `create()`, `create_partial()`, `create_iterable()` calls | | Response Model Handling | Passes response models to the processing pipeline | #### Supported Providers The client architecture supports multiple providers through a consistent interface: ```python # OpenAI client = instructor.from_provider("openai/gpt-4o") # Anthropic client = instructor.from_provider("anthropic/claude-3-5-sonnet") # Google client = instructor.from_provider("google/gemini-pro") # Ollama (local) client = instructor.from_provider("ollama/llama3.2") # Groq client = instructor.from_provider("groq/llama-3.1-8b-instant") ``` #### Core Client Interface The unified client provides these primary methods: | Method | Purpose | |--------|---------| | `create()` | Standard response generation with full validation | | `create_partial()` | Streaming partial responses for progressive validation | | `create_iterable()` | Iterative generation for list/collection outputs | | `create_with_completion()` | Returns both the parsed response and completion details | 资料来源：[examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ### 2. Hooks System (`instructor/core/hooks.py`) The hooks system provides event-driven extensibility, allowing developers to intercept and respond to various stages of the LLM interaction lifecycle. #### Available Hook Events | Hook Event | Trigger | Common Use Cases | |------------|---------|------------------| | `on_request` | Before sending request to LLM | Logging, token counting | | `on_response` | After receiving response | Metrics collection | | `on_retry` | Before retry attempt | Retry count logging | | `on_validation_error` | When validation fails | Custom error handling | | `on_parse_error` | When response parsing fails | Debugging, fallback logic | #### Hook Handler Structure ```mermaid graph LR A[LLM Request] --> B[on_request Hooks] B --> C[API Call] C --> D[on_response Hooks] D --> E{Validation} E -->|Pass| F[on_success Hooks] E -->|Fail| G[on_validation_error Hooks] F --> H[Return Response] G --> I[Retry Logic] I --> J[on_retry Hooks] ``` #### Hook Implementation Pattern ```python from instructor.hooks import Hooks, HookEvent class LoggingHooks(Hooks): def on_request(self, request, **kwargs): print(f"🔍 Request: {request}") def on_response(self, response, **kwargs): print(f"✅ Response received") # Attach hooks to client client = instructor.from_provider("openai/gpt-4o") client.attach_hooks(LoggingHooks()) ``` 资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) ### 3. Retry Mechanism (`instructor/core/retry.py`) The retry module handles automatic retries when validation fails, implementing exponential backoff and maximum retry limits. #### Retry Configuration | Parameter | Default | Description | |-----------|---------|-------------| | `max_retries` | 3 | Maximum number of retry attempts | | `initial_delay` | 1.0 | Initial delay between retries (seconds) | | `backoff_factor` | 2.0 | Multiplier for delay on each retry | | `max_delay` | 60.0 | Maximum delay between retries (seconds) | #### Retry Flow ```mermaid graph TD A[Initial Call] --> B{Validation Pass?} B -->|Yes| C[Return Response] B -->|No| D{Retry Count < Max?} D -->|Yes| E[Apply Backoff] E --> F[Log Error] F --> A D -->|No| G[Raise Exception] ``` #### Custom Retry with Field Validators ```python from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int @field_validator('age') def validate_age(cls, v): if v < 0: raise ValueError('Age must be positive') return v # Instructor automatically retries when validation fails user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ### 4. Response Processing (`instructor/process_response.py`) The response processing module handles parsing LLM outputs into structured Pydantic models, including text parsing, JSON extraction, and model validation. #### Processing Pipeline | Stage | Component | Function | |-------|-----------|----------| | 1 | Raw Response | Receive response from LLM provider | | 2 | Content Extraction | Extract text content from provider-specific format | | 3 | JSON Parsing | Parse JSON from text content | | 4 | Model Instantiation | Create Pydantic model instance | | 5 | Validation | Run Pydantic validators | | 6 | Error Handling | Trigger retries or raise exceptions | #### Validation Error Handling ```python from typing_extensions import Annotated from pydantic import BaseModel, BeforeValidator class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] try: qa: QuestionAnswerNoEvil = client.chat.completions.create( model="gpt-3.5-turbo", response_model=QuestionAnswerNoEvil, messages=[...], ) except Exception as e: print(e) # Handles validation errors ``` #### LLM-Based Validation The response processor supports `llm_validator` for semantic validation beyond Pydantic type checking: ```python from instructor import llm_validator class OutputModel(BaseModel): reasoning: Annotated[str, BeforeValidator(llm_validator("be logical"))] answer: Annotated[str, BeforeValidator(llm_validator("be concise"))] ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ## Provider Architecture ### Provider Organization The `providers/` directory follows a consistent structure across all supported providers: ``` providers/ ├── provider_name/ │ ├── __init__.py │ ├── client.py # Provider-specific client factory │ └── utils.py # Provider-specific utilities ``` #### Provider Categories | Category | Providers | Characteristics | |----------|-----------|-----------------| | Full Implementation | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | Custom client.py + utils.py | | Simplified | genai, groq, vertexai | client.py only | | Reference | openai | utils.py only (core implementation) | 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ### Provider Detection The unified client automatically detects the provider from the model string format: ```python # Format: provider/model-name client = instructor.from_provider("openai/gpt-4o") # - Provider: openai # - Model: gpt-4o client = instructor.from_provider("anthropic/claude-3-5-sonnet") # - Provider: anthropic # - Model: claude-3-5-sonnet ``` ## Data Flow Diagram ```mermaid sequenceDiagram participant User participant Client participant Provider participant Processor participant Validator participant Hooks User->>Client: create(response_model, messages) Client->>Hooks: on_request Client->>Provider: API Call Provider->>Client: Raw Response Client->>Processor: Parse Response Processor->>Validator: Validate Model Validator-->>Processor: Valid/Invalid alt Valid Processor->>Client: Parsed Response Client->>Hooks: on_response Client-->>User: Typed Response else Invalid Processor->>Hooks: on_validation_error Client->>Hooks: on_retry Client->>Provider: Retry API Call Note over Client: Loop until max_retries end ``` ## Configuration Options ### Client Configuration | Option | Type | Default | Description | |--------|------|---------|-------------| | `response_model` | Pydantic Model | Required | The expected response structure | | `max_retries` | int | 3 | Maximum validation retry attempts | | `validation_context` | dict | None | Additional context for validators | | `max_tokens` | int | Provider default | Maximum output tokens | | `temperature` | float | Provider default | Sampling temperature | ### Provider-Specific Configuration ```python # With API keys directly client = instructor.from_provider( "openai/gpt-4o", api_key="sk-..." ) client = instructor.from_provider( "anthropic/claude-3-5-sonnet", api_key="sk-ant-..." ) # With custom settings client = instructor.from_provider( "openai/gpt-4o", api_key="sk-...", max_retries=5, timeout=30.0 ) ``` ## Key Design Patterns ### 1. Factory Pattern The `from_provider()` factory method creates appropriate client instances based on the provider string: ```python def from_provider(provider: str, **kwargs) -> Instructor: """Factory function to create provider-specific client.""" ``` ### 2. Adapter Pattern Each provider implements a consistent interface while handling provider-specific nuances: ```mermaid graph TD A[Instructor API] --> B[Provider Adapter] B --> C[OpenAI Adapter] B --> D[Anthropic Adapter] B --> E[Google Adapter] B --> F[Other Providers] ``` ### 3. Decorator Pattern Hooks provide a way to extend functionality without modifying core classes: ```python @hooks.on_response def log_response(response): # Logging functionality pass ``` ## Error Handling ### Error Types | Error Type | Cause | Recovery Action | |------------|-------|------------------| | `ValidationError` | Pydantic validation fails | Automatic retry with error message | | `ParseError` | JSON parsing fails | Automatic retry | | `MaxRetriesExceeded` | All retries exhausted | Raise exception to user | | `APIError` | Provider API failure | Retry with backoff | ### Exception Flow ```mermaid graph TD A[API Call] --> B{Success?} B -->|No| C[API Error] C --> D{Retry < Max?} D -->|Yes| E[Backoff] E --> A D -->|No| F[Raise APIError] B -->|Yes| G[Parse Response] G --> H{Parse Success?} H -->|No| I[Parse Error] I --> D H -->|Yes| J[Validate Model] J --> K{Valid?} K -->|Yes| L[Return Result] K -->|No| M[Validation Error] M --> D ``` ## Summary The Core Components Architecture of Instructor provides: 1. **Unified Client Interface** - Single API across all LLM providers 2. **Automatic Validation** - Pydantic-based response validation 3. **Smart Retries** - Automatic retry with exponential backoff 4. **Extensible Hooks** - Event-driven customization 5. **Provider Abstraction** - Consistent patterns across providers This architecture enables developers to focus on application logic while Instructor handles the complexities of structured LLM outputs, validation, and error recovery. --- ## Response Models and Type Safety ### 相关页面相关主题：[Validation and Retry Mechanisms](#validation-retries)

相关源码文件

以下源码文件用于生成本页说明： - [docs/concepts/models.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/models.md) - [docs/concepts/fields.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/fields.md) - [docs/learning/getting_started/response_models.md](https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/response_models.md) - [instructor/processing/schema.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/schema.py)

# Response Models and Type Safety ## Overview Instructor provides robust **Response Models** and **Type Safety** mechanisms that enable structured, validated outputs from Large Language Models. By leveraging Pydantic's validation system, Instructor ensures that LLM responses conform to expected schemas while automatically retrying failed validations. ## What are Response Models? Response Models are Pydantic `BaseModel` classes that define the expected structure and types of LLM outputs. They serve as a contract between your application and the LLM, ensuring type-safe, validated responses. ```python from pydantic import BaseModel class User(BaseModel): name: str age: int ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Core Architecture ```mermaid graph TD A[LLM API Call] --> B[Instructor Client] B --> C[Response Model Definition] C --> D[Pydantic Schema Validation] D --> E{Validation Pass?} E -->|Yes| F[Return Validated Object] E -->|No| G[Extract Error Message] G --> H[Retry with Error Context] H --> B ``` ## Using Response Models ### Basic Usage ```python from instructor import from_provider from pydantic import BaseModel client = instructor.from_provider("openai/gpt-4o") class User(BaseModel): name: str age: int user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "Extract: Jason is 28 years old"}], ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ### Nested Response Models Response Models support nested structures for complex data: ```python class Address(BaseModel): street: str city: str country: str class UserProfile(BaseModel): name: str age: int address: Address ``` ## Field Validators Pydantic's `@field_validator` decorator enables custom validation logic for model fields. ### Basic Validation ```python from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int @field_validator('age') def validate_age(cls, v): if v < 0: raise ValueError('Age must be positive') return v ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ### Validation with Regex ```python from pydantic import field_validator class EmailModel(BaseModel): email: str @field_validator('email') def validate_email_format(cls, v): if '@' not in v: raise ValueError('Invalid email format') return v.lower() ``` ## LLM Validators Instructor provides `llm_validator` for content-based validation using the LLM itself. ### Setup ```python from typing_extensions import Annotated from pydantic import BaseModel, BeforeValidator from instructor import llm_validator class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ### Validation Workflow ```mermaid graph TD A[LLM Generates Response] --> B[Apply BeforeValidator] B --> C[LLM Validator Check] C --> D{Validation Pass?} D -->|Yes| E[Accept Response] D -->|No| F[Raise Assertion Error] F --> G[Retry with Context] ``` ## Automatic Retries When validation fails, Instructor automatically retries the request with the error message included. ### Retry Configuration ```python qa: QuestionAnswerNoEvil = openai.ChatCompletion.create( model="gpt-3.5-turbo", response_model=QuestionAnswerNoEvil, max_retries=2, # Number of retry attempts messages=[ { "role": "system", "content": "You are a system that answers questions based on the context.", }, { "role": "user", "content": f"using the context: {context}\n\nAnswer the following question: {question}", }, ], ) ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ### Retry Behavior | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `max_retries` | `int` | `1` | Maximum number of retry attempts on validation failure | | `allow_override` | `bool` | `False` | Allows LLM to override validation with special flag | ## Error Handling ### Catching Validation Errors ```python try: qa: QuestionAnswerNoEvil = openai.ChatCompletion.create( model="gpt-3.5-turbo", response_model=QuestionAnswerNoEvil, messages=[ {"role": "system", "content": "Answer questions based on context."}, {"role": "user", "content": f"context: {context}\nQuestion: {question}"}, ], ) except Exception as e: print(f"Validation failed: {e}") ``` ### Error Output Example ``` 1 validation error for QuestionAnswerNoEvil answer Assertion failed, The statement promotes sin and debauchery, which is objectionable. ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ## Supported Data Types | Type | Description | Example | |------|-------------|---------| | `str` | String text | `name: str` | | `int` | Integer numbers | `age: int` | | `float` | Decimal numbers | `price: float` | | `bool` | Boolean values | `is_active: bool` | | `list[T]` | Lists of type T | `tags: list[str]` | | `dict` | Dictionary objects | `metadata: dict` | | `enum` | Enumeration values | `status: Status` | | `Optional[T]` | Nullable values | `nickname: Optional[str]` | ## Complete Example: User Extraction ```python from instructor import from_provider from pydantic import BaseModel, field_validator client = instructor.from_provider("openai/gpt-4o") class User(BaseModel): name: str age: int email: str @field_validator('email') def validate_email(cls, v): if '@' not in v: raise ValueError('Invalid email address') return v.lower() @field_validator('age') def validate_age(cls, v): if v < 0 or v > 150: raise ValueError('Age must be between 0 and 150') return v # Automatic validation and retries user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "John is 35 years old, email: John@Example.com"}], ) print(f"Name: {user.name}") # John print(f"Age: {user.age}") # 35 print(f"Email: {user.email}") # john@example.com ``` ## Best Practices 1. **Define clear schemas**: Use descriptive field names and type hints 2. **Add validators early**: Catch invalid data at the source 3. **Set appropriate retry limits**: Balance between reliability and cost 4. **Use `allow_override` wisely**: Only when LLM feedback is acceptable 5. **Handle exceptions**: Always wrap calls in try/except for production code ## Related Concepts - [Fields Documentation](https://github.com/567-labs/instructor/blob/main/docs/concepts/fields.md) - Advanced field configuration - [Hooks System](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) - Request/response lifecycle hooks - [Validations Examples](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) - Custom validation patterns --- ## Validation and Retry Mechanisms ### 相关页面相关主题：[Response Models and Type Safety](#response-models), [Streaming and Partial Responses](#streaming)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/567-labs/instructor/blob/main/README.md) - [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) - [examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) - [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) - [examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md)

# Validation and Retry Mechanisms ## Overview Instructor provides robust validation and automatic retry mechanisms that work seamlessly with Pydantic models to ensure LLM outputs conform to expected schemas. When an LLM generates a response that fails validation, Instructor automatically retries the request with the validation error message included, allowing the model to self-correct its output. The validation system extends beyond traditional Pydantic validators to include **LLM-based validators** that can check semantic content, tone, safety, and other qualitative aspects of generated text. Combined with automatic retries, this creates a feedback loop that significantly improves extraction reliability without requiring manual intervention. 资料来源：[README.md:1-50]() --- ## Architecture ### Core Components ```mermaid graph TD A[Client Request] --> B[Pydantic Response Model] B --> C[LLM API Call] C --> D[Response Parsing] D --> E{Validation} E -->|Pass| F[Return Validated Object] E -->|Fail| G[Log Error Message] G --> H{Retry Count < max_retries?} H -->|Yes| I[Retry with Error Context] H -->|No| J[Raise Exception] I --> C ``` ### Validation Pipeline 1. **Initial Request**: User submits a request with a Pydantic `response_model` 2. **LLM Invocation**: Instructor calls the provider API with function calling parameters 3. **Response Parsing**: Raw response is parsed into the target Pydantic model 4. **Validation**: Pydantic validators run on the parsed data 5. **Retry Decision**: If validation fails and retries remain, re-invoke with error context 6. **Final Response**: Validated model instance is returned to user 资料来源：[examples/validators/readme.md:1-80]() --- ## Pydantic-Based Validation ### Standard Field Validators Instructor leverages Pydantic's built-in validation system. Fields defined in response models are automatically validated upon extraction: ```python from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int @field_validator('age') def validate_age(cls, v): if v < 0: raise ValueError('Age must be positive') return v ``` ### Validation Configuration | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `max_retries` | `int` | `3` | Maximum retry attempts after validation failure | | `response_model` | `BaseModel` | Required | Pydantic model defining expected output structure | | `validation_context` | `dict` | `None` | Additional context passed to validators | 资料来源：[README.md:60-90]() --- ## LLM-Based Validation ### Overview The `llm_validator` function enables content-aware validation using the LLM itself. This is useful for semantic checks that cannot be expressed as simple schema rules: ```python from typing_extensions import Annotated from pydantic import BeforeValidator from instructor import llm_validator class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] ``` ### How LLM Validation Works ```mermaid sequenceDiagram participant User participant Instructor participant LLM participant Validator User->>Instructor: Create response with llm_validator Instructor->>LLM: Initial request LLM-->>Instructor: Response Instructor->>Validator: Validate content Validator->>LLM: Check against constraint alt Validation Passes Validator-->>Instructor: Valid Instructor-->>User: Return model else Validation Fails Validator-->>Instructor: Assertion failed: {reason} Instructor->>LLM: Retry with error message LLM-->>Instructor: Corrected response Instructor->>Validator: Re-validate end ``` ### Validator Parameters | Parameter | Type | Description | |-----------|------|-------------| | `criteria` | `str` | The validation rule or constraint | | `allow_override` | `bool` | Whether the validator can be bypassed with `allow=True` | | `model` | `str` | Optional model to use for validation (defaults to response model) | 资料来源：[examples/validators/readme.md:60-120]() --- ## Automatic Retry Mechanism ### Retry Flow When validation fails, Instructor automatically retries the request. The retry process includes: 1. **Error Capture**: The validation error message is extracted 2. **Context Building**: Error details are formatted into a user message 3. **Retry Execution**: The original request is repeated with error context 4. **Iteration**: Process repeats until success or `max_retries` is exhausted ```python user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], max_retries=3, # Retry up to 3 times ) ``` ### Retry Behavior | Scenario | Behavior | |----------|----------| | Validation passes | Return validated object immediately | | Validation fails (retries available) | Retry with error context | | Validation fails (no retries left) | Raise `ValidationError` | | API error | Retry with exponential backoff | 资料来源：[README.md:75-95]() --- ## Streaming with Partial Validation Instructor supports streaming responses with partial validation, allowing real-time feedback as objects are generated: ```python from instructor import Partial for partial_user in client.chat.completions.create( response_model=Partial[User], messages=[{"role": "user", "content": "..."}], stream=True, ): print(partial_user) # Output progression: # User(name=None, age=None) # User(name="John", age=None) # User(name="John", age=25) ``` ### Partial Validation States ```mermaid graph LR A[Start] --> B{name != None} B -->|No| C[Partial: User(name=None, ...)] B -->|Yes| D{age != None} D -->|No| E[Partial: User(name="...", ...)] D -->|Yes| F[Complete: User(...)] ``` 资料来源：[README.md:95-110]() --- ## Hooks for Validation Monitoring Instructor provides hooks that allow monitoring of validation events during the request lifecycle: ```mermaid graph LR A[Request Start] --> B[Parse Hook] B --> C[LLM Call] C --> D{Validation} D --> E[Success Hook] D --> F[Error Hook] E --> G[Return Result] F --> H[Retry Hook] H -->|Has Retries| C H -->|No Retries| I[Raise Exception] ``` ### Available Hook Types | Hook | Trigger | Use Case | |------|---------|----------| | `on_request_start` | Before API call | Log request details | | `on_response` | Successful response | Track token usage | | `on_parse_error` | JSON parsing failure | Debug malformed output | | `on_retry` | Before retry attempt | Log retry attempts | | `on_validation_error` | Validation failure | Track failed validations | 资料来源：[examples/hooks/README.md:1-30]() --- ## Error Handling Patterns ### Handling Validation Errors ```python try: qa: QuestionAnswerNoEvil = openai.ChatCompletion.create( model="gpt-3.5-turbo", response_model=QuestionAnswerNoEvil, messages=[{"role": "user", "content": "..."}], ) except Exception as e: print(f"Validation failed after retries: {e}") ``` ### Common Validation Error Types | Error Type | Cause | Resolution | |------------|-------|------------| | `ValidationError` | Pydantic validation failure | Check field constraints | | `ParseError` | Malformed JSON response | Model may need adjustment | | `AssertionError` | LLM validator rejection | Review validation criteria | 资料来源：[examples/validators/readme.md:100-140]() --- ## Integration with Batch Processing Validation and retry mechanisms are also available in batch processing scenarios: ```python from instructor.processing import BatchProcessor batch = BatchProcessor( response_model=User, max_retries=3, on_validation_error=lambda e: log_error(e) ) batch.process(messages_file="messages.jsonl") ``` ### Batch Validation Features - Parallel validation of batch items - Per-item retry tracking - Aggregated error reporting - Configurable failure thresholds 资料来源：[examples/batch_api/README.md:1-60]() --- ## Best Practices ### 1. Define Clear Validation Rules ```python # Good: Specific, enforceable rules @field_validator('email') def validate_email(cls, v): if '@' not in v: raise ValueError('Invalid email format') return v # Good: LLM validator for semantic checks llm_validator("response should be concise and factual") ``` ### 2. Set Appropriate Retry Limits | Use Case | Recommended `max_retries` | |----------|--------------------------| | Simple extraction | 1-2 | | Complex nested structures | 3-5 | | LLM-validated content | 2-3 | ### 3. Use Descriptive Error Messages Validation error messages are passed to the LLM during retries. Clear, actionable error messages improve retry success rates. --- ## Summary Instructor's validation and retry mechanisms provide a powerful abstraction layer for reliable LLM output extraction: - **Pydantic Integration**: Leverage existing validation patterns - **LLM-Based Validation**: Check semantic content quality - **Automatic Retries**: Self-correcting extraction pipeline - **Streaming Support**: Real-time partial validation - **Hook System**: Observable validation lifecycle Together, these components create a robust system for building production-grade LLM applications with predictable, validated outputs. 资料来源：[README.md:1-120](), [examples/validators/readme.md:1-150]() --- ## Streaming and Partial Responses ### 相关页面相关主题：[Validation and Retry Mechanisms](#validation-retries)

相关源码文件

以下源码文件用于生成本页说明： - [instructor/dsl/partial.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/partial.py) - [instructor/dsl/iterable.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/iterable.py) - [docs/concepts/partial.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/partial.md) - [docs/concepts/iterable.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/iterable.md) - [examples/partial_streaming/run.py](https://github.com/567-labs/instructor/blob/main/examples/partial_streaming/run.py)

# Streaming and Partial Responses ## Overview Streaming and partial responses are core features in Instructor that enable real-time processing of LLM outputs. Instead of waiting for the complete response to be generated, these features allow developers to receive and process data incrementally as it's being generated by the model. The primary purpose of streaming support is to: - Provide faster perceived latency by displaying partial results immediately - Enable real-time UI updates for interactive applications - Support progressive data extraction for long-form content - Allow applications to start processing data before the entire response is complete 资料来源：[README.md:streaming support]() ## Architecture Instructor implements streaming through two complementary abstractions: 1. **Partial** - Represents a partially validated response model 2. **Iterable** - Represents a stream of validated response models ### Data Flow Architecture ```mermaid graph TD A[LLM API Streaming Response] --> B[Instructor Response Handler] B --> C{Response Mode} C -->|Partial Mode| D[Partial Validator] C -->|Iterable Mode| E[Iterable Validator] D --> F[Partial Response Model] E --> G[Validated Response Objects] F --> H[Application Consumer] G --> H ``` ### Component Overview | Component | Purpose | File Location | |-----------|---------|---------------| | `Partial[T]` | Generic wrapper for partial response models | `instructor/dsl/partial.py` | | `Iterable[T]` | Generic wrapper for streaming response models | `instructor/dsl/iterable.py` | | Response Handler | Processes streaming chunks from LLM providers | Core client implementation | | Validation Pipeline | Validates each partial/iterable chunk | Instructor DSL layer | 资料来源：[instructor/dsl/partial.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/partial.py) 资料来源：[instructor/dsl/iterable.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/iterable.py) ## Partial Responses ### What Are Partial Responses? Partial responses enable receiving incrementally validated data as the LLM generates content. When using `Partial[T]`, each streamed chunk contains a validated response model where some fields may be `None` until the model finishes generating them. ### Usage Pattern ```python from instructor import Partial from pydantic import BaseModel class User(BaseModel): name: str age: int # Stream partial responses as they're generated for partial_user in client.chat.completions.create( response_model=Partial[User], messages=[{"role": "user", "content": "..."}], stream=True, ): print(partial_user) ``` ### Evolution of Partial Response During streaming, the response model evolves as follows: ```python # Initial state - no fields populated # User(name=None, age=None) # After name is generated # User(name="John", age=None) # After full generation complete # User(name="John", age=25) ``` 资料来源：[README.md:Streaming support]() 资料来源：[docs/concepts/partial.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/partial.md) ## Iterable Responses ### What Are Iterable Responses? Iterable responses handle streams of complete, validated response models. Unlike `Partial[T]` which shows evolution of a single response, `Iterable[T]` represents multiple discrete responses that can be streamed from the LLM. ### Usage Pattern ```python from instructor import Iterable class TaskResult(BaseModel): task_id: str result: str status: str # Stream multiple validated responses for task in client.chat.completions.create( response_model=Iterable[TaskResult], messages=[{"role": "user", "content": "Process these items..."}], stream=True, ): print(f"Task {task.task_id}: {task.status}") ``` 资料来源：[instructor/dsl/iterable.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/iterable.py) 资料来源：[docs/concepts/iterable.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/iterable.md) ## API Reference ### Client Method Signature Both partial and iterable streaming use the standard client creation method with additional parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `response_model` | `Type[BaseModel]` | Required | The Pydantic model for validation | | `messages` | `List[dict]` | Required | Conversation messages | | `stream` | `bool` | `False` | Enable streaming mode | | `max_retries` | `int` | `3` | Maximum retry attempts on validation failure | | `**kwargs` | Various | Provider-specific | Additional provider parameters | ### Response Type Resolution | Response Model Wrapper | Return Type | Use Case | |------------------------|-------------|----------| | `response_model=User` | `User` | Complete, validated single response | | `response_model=Partial[User]` | `Generator[User, None, None]` | Progressive single response | | `response_model=Iterable[User]` | `Generator[User, None, None]` | Stream of validated responses | 资料来源：[examples/partial_streaming/run.py](https://github.com/567-labs/instructor/blob/main/examples/partial_streaming/run.py) ## Provider Compatibility ### Universal Streaming Support Streaming is supported across all major LLM providers through a unified interface: ```python # OpenAI client = instructor.from_provider("openai/gpt-4o") for partial in client.chat.completions.create( response_model=Partial[User], messages=[...], stream=True, ): print(partial) # Anthropic client = instructor.from_provider("anthropic/claude-3-5-sonnet") for partial in client.chat.completions.create( response_model=Partial[User], messages=[...], stream=True, ): print(partial) # Google client = instructor.from_provider("google/gemini-pro") for partial in client.chat.completions.create( response_model=Partial[User], messages=[...], stream=True, ): print(partial) ``` ### Provider Response Handling Each provider implements streaming through provider-specific response handlers: ```mermaid graph LR A[Provider API] --> B[Provider Utils] B --> C[Standardized Chunk Format] C --> D[Instructor DSL] D --> E[Partial/Iterable Validator] E --> F[Validated Response] ``` 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ## Validation Behavior ### Validation During Streaming Partial and iterable responses undergo the same validation as non-streaming responses. The key difference is that validation occurs on each streamed chunk rather than on a complete response. ### Validation Pipeline Flow ```mermaid graph TD A[Stream Chunk Received] --> B[Parse to Response Model] B --> C{Validation Pass?} C -->|Yes| D[Yield Validated Partial] C -->|No| E{Retry Available?} E -->|Yes| F[Retry with Error Context] E -->|No| G[Raise Validation Error] D --> H[Next Chunk] H --> A ``` ### Error Handling When validation fails during streaming, Instructor can retry automatically if `max_retries` is configured: ```python for partial_user in client.chat.completions.create( response_model=Partial[User], messages=[{"role": "user", "content": "..."}], stream=True, max_retries=3, # Automatic retry on validation failure ): print(partial_user) ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ## Use Cases ### Real-Time UI Updates Partial responses are ideal for applications requiring immediate visual feedback: ```python from instructor import Partial class SearchResult(BaseModel): title: str url: str snippet: str # Update UI as results arrive for partial_result in client.chat.completions.create( response_model=Partial[SearchResult], messages=[{"role": "user", "content": f"Search for: {query}"}], stream=True, ): update_ui(partial_result) # Progressive rendering ``` ### Long-Running Task Processing Iterable responses suit scenarios where the LLM generates multiple distinct outputs: ```python class AnalysisReport(BaseModel): section: str findings: List[str] confidence: float for report_section in client.chat.completions.create( response_model=Iterable[AnalysisReport], messages=[{"role": "user", "content": "Analyze this document..."}], stream=True, ): save_section(report_section) ``` ### Progressive Data Extraction Extract complex nested structures incrementally: ```python class Document(BaseModel): title: str author: str sections: List["Section"] class Section(BaseModel): heading: str content: str for partial_doc in client.chat.completions.create( response_model=Partial[Document], messages=[{"role": "user", "content": "Extract document structure..."}], stream=True, ): display_preview(partial_doc) ``` ## Best Practices ### Performance Considerations | Practice | Recommendation | Rationale | |----------|----------------|-----------| | Batch Processing | Use `Iterable[T]` for multiple items | Reduces API call overhead | | UI Responsiveness | Prefer `Partial[T]` for progressive updates | Lower perceived latency | | Validation Overhead | Set appropriate `max_retries` | Balance reliability vs. performance | ### Error Handling Strategy ```python try: for partial in client.chat.completions.create( response_model=Partial[User], messages=[...], stream=True, max_retries=3, ): process(partial) except ValidationError as e: handle_validation_failure(e) except Exception as e: handle_stream_error(e) ``` ### Memory Efficiency When processing large streams, consume the generator incrementally rather than collecting all results: ```python # Memory efficient - processes one at a time for item in client.chat.completions.create( response_model=Iterable[LargeModel], messages=[...], stream=True, ): write_to_disk(item) # Memory intensive - collects all results all_items = list(client.chat.completions.create( response_model=Iterable[LargeModel], messages=[...], stream=True, )) ``` ## Related Concepts - **Retry Logic**: Streaming integrates with Instructor's automatic retry mechanism for validation failures - **Hooks System**: Hooks can be attached to streaming operations for monitoring and logging - **Provider Architecture**: Each LLM provider implements streaming through provider-specific utilities ## Summary Streaming and partial responses in Instructor provide powerful mechanisms for real-time data processing with LLM outputs. The `Partial[T]` wrapper enables progressive validation of single responses, while `Iterable[T]` supports streaming multiple discrete responses. Both features maintain full integration with Pydantic validation, retry logic, and all supported LLM providers through a unified API. --- ## LLM Provider Support ### 相关页面相关主题：[Unified Provider Interface](#from-provider), [Installation and Setup](#installation)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/567-labs/instructor/blob/main/README.md) - [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) - [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) - [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) - [examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) - [examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md)

# LLM Provider Support ## Overview Instructor provides a unified API for working with multiple Large Language Model (LLM) providers. The library abstracts provider-specific implementations behind a common interface, allowing developers to switch between providers without modifying their application logic. The `from_provider()` method serves as the primary entry point for initializing clients across all supported providers 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md). ## Supported Providers Instructor supports the following LLM providers through a consistent API: | Provider | Client Function | Model Examples | |----------|------------------|----------------| | OpenAI | `from_provider("openai/...")` | gpt-4o, gpt-4o-mini, gpt-4-turbo | | Anthropic | `from_provider("anthropic/...")` | claude-3-5-sonnet, claude-3-opus | | Google | `from_provider("google/...")` | gemini-2.0-flash-001, gemini-pro | | Ollama | `from_provider("ollama/...")` | llama3.2 (local models) | | Groq | `from_provider("groq/...")` | llama-3.1-8b-instant | | Cohere | `from_provider("cohere/...")` | Command R+ | | Mistral | `from_provider("mistral/...")` | Mistral Large | | Fireworks | `from_provider("fireworks/...")` | fireworks models | | Perplexity | `from_provider("perplexity/...")` | perplexity models | | Cerebras | `from_provider("cerebras/...")` | cerebras models | | XAI | `from_provider("xai/...")` | xai models | | Writer | `from_provider("writer/...")` | writer models | | VertexAI | `from_provider("vertexai/...")` | vertexai models | | Bedrock | `from_provider("bedrock/...")` | bedrock models | 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Provider Architecture ### Directory Structure Each provider is organized in its own subdirectory within `instructor/providers/`: ``` providers/ ├── provider_name/ │ ├── __init__.py │ ├── client.py # Provider-specific client factory (optional) │ └── utils.py # Provider-specific utilities (optional) ``` 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ### Provider Classification Providers are categorized based on their implementation complexity: #### Providers with Both `client.py` and `utils.py` These providers require custom response handling logic and utility functions: - **anthropic** - **bedrock** - **cerebras** - **cohere** - **fireworks** - **gemini** - **mistral** - **perplexity** - **writer** - **xai** #### Providers with Only `client.py` These are simpler providers using standard response handling from the core: - **genai** - **groq** - **vertexai** #### Special Case: OpenAI OpenAI doesn't have a `client.py` because `from_openai()` is defined in `core/client.py`. This is because OpenAI is the reference implementation that other providers are based on. 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ## Unified Client API ### Basic Initialization All providers use the same initialization pattern: ```python client = instructor.from_provider("provider/model-name") ``` ### Usage Example ```python from instructor import from_provider # OpenAI client = instructor.from_provider("openai/gpt-4o") # Anthropic client = instructor.from_provider("anthropic/claude-3-5-sonnet") # Google client = instructor.from_provider("google/gemini-pro") # Ollama (local) client = instructor.from_provider("ollama/llama3.2") ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ### API Key Configuration API keys can be passed directly to the `from_provider()` method: ```python # OpenAI with explicit API key client = instructor.from_provider("openai/gpt-4o", api_key="sk-...") # Anthropic with explicit API key client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...") # Groq with explicit API key client = instructor.from_provider("groq/llama-3.1-8b-instant", api_key="gsk_...") ``` Alternatively, providers respect environment variables for API key configuration. 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Response Model Integration All providers support Pydantic response models for structured outputs: ```python from pydantic import BaseModel class User(BaseModel): name: str age: int client = instructor.from_provider("openai/gpt-4o") user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ### Validator Support Providers work seamlessly with Pydantic validators: ```python from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int @field_validator('age') def validate_age(cls, v): if v < 0: raise ValueError('Age must be positive') return v # Instructor automatically retries when validation fails user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ### LLM Validators Custom validation using `llm_validator` is supported across all providers: ```python from typing_extensions import Annotated from pydantic import BeforeValidator from instructor import llm_validator class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] ``` 资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md) ## Automatic Retries Failed validations are automatically retried with the error message: ```python user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], max_retries=2, ) ``` 资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md) ## Batch Processing Support Providers support batch API operations through the unified `BatchProcessor` interface: ### Supported Batch Operations ```bash # Create batch using CLI instructor batch create \ --messages-file messages.jsonl \ --model "openai/gpt-4o-mini" \ --response-model "examples.User" \ --output-file batch_requests.jsonl # Submit the batch instructor batch create-from-file \ --file-path batch_requests.jsonl \ --model "openai/gpt-4o-mini" ``` ### Provider-Specific Batch Features | Provider | Batch Endpoint | Notes | |----------|----------------|-------| | OpenAI | `client.batches.create()` | Standard batch API | | Anthropic | `client.beta.messages.batches` | Uses beta API endpoints | | Google | Simulation mode | Requires GCS for production | 资料来源：[examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ### Batch Test Script A test script is available to validate batch processing across providers: ```bash # Test OpenAI export OPENAI_API_KEY="your-api-key" python run_batch_test.py create --model "openai/gpt-4o-mini" # Test Anthropic export ANTHROPIC_API_KEY="your-api-key" python run_batch_test.py create --model "anthropic/claude-3-5-sonnet-20241022" # Test Google (simulation mode) python run_batch_test.py create --model "google/gemini-2.0-flash-001" ``` 资料来源：[examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ## Hooks System Providers integrate with Instructor's hooks system for monitoring and debugging: ### Available Hook Events - **Request hooks**: Execute before API calls - **Response hooks**: Execute after successful responses - **Error hooks**: Execute on completion errors - **Retry hooks**: Execute on retry attempts ### Hook Implementation Example ```python def on_request(detail): print(f"🔍 Request: {detail}") def on_response(detail): print(f"✅ Response: {detail}") def on_error(detail): print(f"❌ Error: {detail}") client = instructor.from_provider("openai/gpt-4o") client.attach_hook("request", on_request) client.attach_hook("response", on_response) client.attach_hook("error", on_error) ``` 资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md) ## Fine-tuning Integration All providers support Instructor's fine-tuning capabilities: ```python # Generate fine-tuning data python three_digit_mul.py # Create fine-tuning job instructor jobs create-from-file math_finetunes.jsonl # With validation data instructor jobs create-from-file math_finetunes.jsonl \ --n-epochs 4 \ --validation-file math_finetunes_val.jsonl ``` 资料来源：[examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md) ## Provider Selection Guidelines ### Flowchart: Provider Selection ```mermaid graph TD A[Select Provider] --> B{Need Local Model?} B -->|Yes| C[Ollama] B -->|No| D{Need Specific Capabilities?} D -->|Anthropic Claude| E[Anthropic] D -->|Google Gemini| F[Google] D -->|OpenAI GPT| G[OpenAI] D -->|Low Cost| H[Groq] D -->|Custom| I[Other Providers] G --> J[Create Client] E --> J F --> J C --> J H --> J I --> J J --> K[Use with Response Model] ``` ### Selection Criteria | Use Case | Recommended Provider | |----------|---------------------| | General purpose, best quality | OpenAI GPT-4o | | Long context, reasoning | Anthropic Claude | | Fast inference, cost-effective | Groq | | Multimodal capabilities | Google Gemini | | Local/private deployment | Ollama | | AWS integration | Bedrock | | Complex reasoning tasks | xAI | ## Adding New Providers When adding a new provider to Instructor: 1. Create a new subdirectory under `instructor/providers/` 2. Add an `__init__.py` file 3. Implement `client.py` for the provider factory function 4. Add `utils.py` for provider-specific response handling 5. Update the unified `from_provider()` dispatcher 资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md) ## Error Handling ### Common Provider Errors | Error | Cause | Solution | |-------|-------|----------| | `API key not set` | Missing environment variable | Set appropriate API key | | `Invalid model format` | Incorrect model string format | Use `provider/model-name` format | | `Unsupported provider` | Provider not in registry | Use supported provider names | | `Rate limit exceeded` | Too many requests | Implement backoff or reduce concurrency | ### Error Recovery Providers support automatic retry with exponential backoff for transient failures: ```python user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], max_retries=3, ) ``` 资料来源：[examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) ## See Also - [Core Client Implementation](../instructor/client.md) - [Response Models and Validation](./response_models.md) - [Hooks System](./hooks.md) - [Batch Processing](./batch_processing.md) - [Fine-tuning](./fine_tuning.md) --- ## Unified Provider Interface ### 相关页面相关主题：[LLM Provider Support](#providers), [Core Components Architecture](#core-components)

Related Source Files

The following source files were referenced (note: some files were not available in the current context): - [instructor/auto_client.py](https://github.com/567-labs/instructor/blob/main/instructor/auto_client.py) - Main unified client implementation - [docs/concepts/from_provider.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/from_provider.md) - Conceptual documentation for the provider interface - [instructor/utils/providers.py](https://github.com/567-labs/instructor/blob/main/instructor/utils/providers.py) - Provider utility functions - [README.md](https://github.com/567-labs/instructor/blob/main/README.md) - Primary documentation - [providers/README.md](https://github.com/567-labs/instructor/blob/main/providers/README.md) - Provider organization documentation - [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md) - Batch API with provider examples

# Unified Provider Interface ## Overview The **Unified Provider Interface** is a core architectural feature of the Instructor library that provides a single, consistent API for interacting with multiple Large Language Model (LLM) providers. This abstraction eliminates provider-specific code patterns and allows developers to switch between different LLM backends without modifying their application logic. The unified interface is accessed through the `from_provider()` factory function, which accepts provider/model strings in the format `"provider/model-name"` and returns a configured client instance that follows a standardized interface. 资料来源：[README.md](README.md) ## Architecture ### Core Design Principles 1. **Provider Agnosticism**: All supported providers implement the same method signatures 2. **Automatic Model Detection**: Provider is inferred from the model string prefix 3. **Transparent Retries**: Failed validations are automatically retried with error context 4. **Type Safety**: Full Pydantic integration for response validation ### Supported Providers The unified interface supports multiple LLM providers through a consistent abstraction layer: | Provider | Model Prefix | Special Features | |----------|--------------|------------------| | OpenAI | `openai/` | Reference implementation | | Anthropic | `anthropic/` | Beta API endpoints | | Google | `google/` | Gemini Pro/Vision | | Ollama | `ollama/` | Local models | | Groq | `groq/` | Fast inference | | Mistral | `mistral/` | European models | | Cohere | `cohere/` | Command models | | AWS Bedrock | `bedrock/` | Cloud deployment | | Cerebras | `cerebras/` | Optimized inference | | Fireworks | `fireworks/` | High performance | | Perplexity | `perplexity/` | Search-focused | | Writer | `writer/` | Enterprise content | | XAI | `xai/` | Elon Musk's xAI | 资料来源：[README.md](README.md), [providers/README.md](providers/README.md) ## Usage ### Basic Initialization ```python import instructor # Create unified client for any provider client = instructor.from_provider("openai/gpt-4o") # Use the same API regardless of provider user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` ### Provider Comparison ```python # OpenAI client = instructor.from_provider("openai/gpt-4o") # Anthropic client = instructor.from_provider("anthropic/claude-3-5-sonnet") # Google client = instructor.from_provider("google/gemini-pro") # Ollama (local) client = instructor.from_provider("ollama/llama3.2") ``` 资料来源：[README.md](README.md) ### API Key Configuration The unified interface supports multiple ways to provide API credentials: | Method | Description | |--------|-------------| | Environment Variables | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc. | | Direct Parameter | `client = from_provider("openai/gpt-4o", api_key="sk-...")` | ```python # With API keys directly (no environment variables needed) client = instructor.from_provider("openai/gpt-4o", api_key="sk-...") client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...") client = instructor.from_provider("groq/llama-3.1-8b-instant", api_key="gsk_...") ``` 资料来源：[README.md](README.md) ## Provider Directory Structure Each provider implementation follows a standardized directory structure: ``` providers/ ├── provider_name/ │ ├── __init__.py │ ├── client.py # Provider-specific client factory (optional) │ └── utils.py # Provider-specific utilities (optional) ``` ### Provider Categories **Providers with both `client.py` and `utils.py`:** - anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai **Providers with only `client.py`:** - genai, groq, vertexai **Special Case - OpenAI:** - OpenAI doesn't have a `client.py` because `from_openai()` is defined in `core/client.py` - OpenAI is the reference implementation that other providers are based on 资料来源：[providers/README.md](providers/README.md) ## API Methods ### Create Method The primary method for generating structured responses: ```python response = client.chat.completions.create( response_model=User, # Pydantic model messages=[...], model="...", max_retries=3, # Automatic retry on validation failure ) ``` ### Alternative API Patterns For simplified usage, these patterns are also supported: ```python # All equivalent to client.chat.completions.create client.create() client.create_partial() client.create_iterable() client.create_with_completion() ``` 资料来源：[scripts/README.md](scripts/README.md) ## Response Model Integration The unified interface seamlessly integrates with Pydantic for type validation: ### Basic Model Definition ```python from pydantic import BaseModel class User(BaseModel): name: str age: int ``` ### Model with Validation ```python from pydantic import BaseModel, field_validator class User(BaseModel): name: str age: int @field_validator('age') def validate_age(cls, v): if v < 0: raise ValueError('Age must be positive') return v ``` When validation fails, Instructor automatically retries the request with the error message: ```python # Instructor automatically retries when validation fails user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) ``` 资料来源：[README.md](README.md) ## Batch Processing The unified interface supports batch processing across all providers through the `BatchProcessor` class: ```python from instructor.batch import BatchProcessor processor = BatchProcessor() # Create batch with provider detection processor.create_batch( messages=test_messages, model="openai/gpt-4o-mini", response_model=User, ) ``` ### Provider-Specific Batch Support | Provider | Batch API | Notes | |----------|-----------|-------| | OpenAI | `client.batches.create()` | Full support | | Anthropic | `client.beta.messages.batches` | Beta endpoints | | Google | Simulation mode | Requires GCS setup | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) ## Workflow Diagram ```mermaid graph TD A[User Code] --> B[from_provider factory] B --> C{Parse provider/model} C -->|openai| D[OpenAI Client] C -->|anthropic| E[Anthropic Client] C -->|google| F[Google Client] C -->|other| G[Other Provider Client] D --> H[Unified API Layer] E --> H F --> H G --> H H --> I[Provider-Specific Transport] I --> J{Response Validation} J -->|Pass| K[Return Typed Response] J -->|Fail| L[Retry with Error Context] L --> H ``` ## Advanced Configuration ### Custom Validators You can add custom LLM-based validation: ```python from typing_extensions import Annotated from pydantic import BeforeValidator from instructor import llm_validator class QuestionAnswerNoEvil(BaseModel): question: str answer: Annotated[ str, BeforeValidator( llm_validator("don't say objectionable things", allow_override=True) ), ] ``` ### Retry Configuration ```python # Allow retries on validation failure qa = client.chat.completions.create( response_model=QuestionAnswer, max_retries=2, messages=[...], ) ``` 资料来源：[examples/validators/readme.md](examples/validators/readme.md) ## Migration from Legacy Patterns ### Old Patterns to Unified Interface | Old Pattern | Unified Pattern | |-------------|------------------| | `instructor.from_openai(OpenAI())` | `instructor.from_provider("openai/model-name")` | | `instructor.from_anthropic(Anthropic())` | `instructor.from_provider("anthropic/model-name")` | | `instructor.patch(OpenAI())` | `instructor.from_provider("openai/model-name")` | ### Automated Migration Scripts The repository includes scripts to automate migration: ```bash # Replace old patterns automatically python scripts/fix_old_patterns.py --dry-run python scripts/fix_old_patterns.py # Audit documentation for old patterns python scripts/audit_patterns.py ``` 资料来源：[scripts/README.md](scripts/README.md) ## Summary The Unified Provider Interface is a fundamental architectural feature that enables Instructor to work seamlessly across multiple LLM providers. By abstracting provider-specific details behind a common API: - Developers can switch providers without code changes - Response validation works consistently across all providers - Automatic retries provide resilience against transient failures - The Pydantic integration ensures type safety throughout This design philosophy makes Instructor highly adaptable and future-proof, as new providers can be added without affecting existing code. --- --- ## Doramagic 踩坑日志项目：567-labs/instructor 摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Documentation (at least Google-related) is an outdated mess.。 ## 1. 安装坑 · 来源证据：Documentation (at least Google-related) is an outdated mess. - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documentation (at least Google-related) is an outdated mess. - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_b87b003416cd4308bc863f0cd66a68fd | https://github.com/567-labs/instructor/issues/2289 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：v1.13.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.13.0 - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_f3c1e8416a744b51b5691317c10bc5bf | https://github.com/567-labs/instructor/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 3. 配置坑 · 来源证据：v1.12.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.12.0 - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_9b8236f58f8641c586777618a838409f | https://github.com/567-labs/instructor/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 配置坑 · 来源证据：v1.14.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_053ef3382ace48778d05ef006d87cead | https://github.com/567-labs/instructor/releases/tag/v1.14.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 5. 配置坑 · 来源证据：v1.14.3 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.3 - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_d18c003929614c7097d16742ec94cc8c | https://github.com/567-labs/instructor/releases/tag/v1.14.3 | 来源类型 github_release 暴露的待验证使用条件。 ## 6. 配置坑 · 来源证据：v1.14.4 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.4 - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_76987134f9a747d685958a5e98f3b51a | https://github.com/567-labs/instructor/releases/tag/v1.14.4 | 来源类型 github_release 暴露的待验证使用条件。 ## 7. 配置坑 · 来源证据：v1.15.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.15.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_430369db61e440e5a4b575e2b3618464 | https://github.com/567-labs/instructor/releases/tag/v1.15.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 8. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass. ## 9. 运行坑 · 来源证据：v1.14.2 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.14.2 - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_fd561faf78f147518bcda7a0370a9a4f | https://github.com/567-labs/instructor/releases/tag/v1.14.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 10. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing ## 11. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium ## 12. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium ## 13. 安全/权限坑 · 来源证据：Catching IncompleteOutputException : not possible as presently documented / tested. - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Catching IncompleteOutputException : not possible as presently documented / tested. - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_dc0f4256859740f8a4cacd1731514783 | https://github.com/567-labs/instructor/issues/2273 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 14. 安全/权限坑 · 来源证据：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto) - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_b982358c78a346bfaa26b428e00968bb | https://github.com/567-labs/instructor/issues/2291 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 15. 安全/权限坑 · 来源证据：bump lightllm upper bound for recent vulnerabililties - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bump lightllm upper bound for recent vulnerabililties - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_2ae9c53479204c778e56a8b4b3feb404 | https://github.com/567-labs/instructor/issues/2290 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 16. 安全/权限坑 · 来源证据：logger.debug in response.py leaks api_key verbatim via new_kwargs - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：logger.debug in response.py leaks api_key verbatim via new_kwargs - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_2076a35fb27a4c119141e9f57acdf9bc | https://github.com/567-labs/instructor/issues/2265 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 17. 安全/权限坑 · 来源证据：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry m… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry message - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_0ab343e8383b4d89bbe8eeea25cc69d8 | https://github.com/567-labs/instructor/issues/2277 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 18. 安全/权限坑 · 来源证据：v1.14.5 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.14.5 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_e73ef57918504fe88cf0af969c414ca1 | https://github.com/567-labs/instructor/releases/tag/v1.14.5 | 来源类型 github_release 暴露的待验证使用条件。 ## 19. 安全/权限坑 · 来源证据：v1.15.1 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.15.1 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_ef102fc17ae84e319f80cfd4cc306eaa | https://github.com/567-labs/instructor/releases/tag/v1.15.1 | 来源类型 github_release 暴露的待验证使用条件。 ## 20. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | issue_or_pr_quality=unknown ## 21. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | release_recency=unknown