Instructor: Структурированные выходные данные для LLM

Получайте надёжный JSON от любой LLM. Построено на Pydantic для валидации, типобезопасности и поддержки IDE.

import instructor
from pydantic import BaseModel


# Define what you want
class User(BaseModel):
    name: str
    age: int


# Extract it from natural language
client = instructor.from_provider("openai/gpt-4o-mini")
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "John is 25 years old"}],
)

print(user)  # User(name='John', age=25)

Вот и всё. Никакого парсинга JSON, никакой обработки ошибок, никаких повторных попыток. Просто определите модель и получите структурированные данные.

Используйте Instructor для быстрого извлечения данных, обращайтесь к PydanticAI, когда вам нужны агенты. Instructor сохраняет простоту и дешевизну рабочих процессов с фокусом на схеме. Если вашему приложению нужны более богатые запуски агентов, встроенная наблюдаемость или общие трассировки, попробуйте PydanticAI. PydanticAI — это официальная среда выполнения агентов от команды Pydantic, добавляющая типизированные инструменты, воспроизводимые наборы данных, оценки и панели мониторинга для продакшена при использовании тех же моделей Pydantic. Погрузитесь в документацию PydanticAI, чтобы узнать, как она расширяет рабочие процессы в стиле Instructor.

Почему Instructor?

Получение структурированных данных от LLM — непростая задача. Вам нужно:

1. Писать сложные JSON-схемы
2. Обрабатывать ошибки валидации
3. Повторять неудачные извлечения
4. Парсить неструктурированные ответы
5. Работать с различными API провайдеров

Instructor решает всё это одним простым интерфейсом:

response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "..."}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "extract_user",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "age": {"type": "integer"},
                    },
                },
            },
        }
    ],
)

# Parse response
tool_call = response.choices[0].message.tool_calls[0]
user_data = json.loads(tool_call.function.arguments)

# Validate manually
if "name" not in user_data:
    # Handle error...
    pass

client = instructor.from_provider("openai/gpt-4")

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

# That's it! user is validated and typed

Установка за секунды

pip install instructor

Или с помощью вашего менеджера пакетов:

uv add instructor
poetry add instructor

Работает с каждым крупным провайдером

Используйте один и тот же код с любым LLM-провайдером:

# 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 (локально)
client = instructor.from_provider("ollama/llama3.2")

# С API-ключами напрямую (без переменных окружения)
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_...")

# Все используют один и тот же API!
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

Готовые для продакшена функции

Автоматические повторные попытки

Неудачные валидации автоматически повторяются с сообщением об ошибке:

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": "..."}],
    max_retries=3,
)

Поддержка потоковой передачи

Передавайте частичные объекты по мере их генерации:

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)
    # User(name=None, age=None)
    # User(name="John", age=None)
    # User(name="John", age=25)

Вложенные объекты

Извлекайте сложные вложенные структуры данных:

from typing import List


class Address(BaseModel):
    street: str
    city: str
    country: str


class User(BaseModel):
    name: str
    age: int
    addresses: List[Address]


# Instructor handles nested objects automatically
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

Используется в продакшене

Нам доверяют более 100 000 разработчиков и компаний, создающих AI-приложения:

• Более 3 млн загрузок в месяц
• Более 10K звёзд на GitHub
• Более 1000 контрибьюторов в сообществе

Среди компаний, использующих Instructor, — команды в OpenAI, Google, Microsoft, AWS и множество стартапов из YC.

Начало работы

Базовое извлечение

Извлекайте структурированные данные из любого текста:

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)

Несколько языков

Простой API Instructor доступен на многих языках:

• Python — Оригинал
• TypeScript — Полная поддержка TypeScript
• Ruby — Реализация на Ruby
• Go — Реализация на Go
• Elixir — Реализация на Elixir
• Rust — Реализация на Rust

Узнайте больше

• Документация — Подробные руководства
• Примеры — Готовые рецепты для копирования
• Блог — Учебные материалы и лучшие практики
• Discord — Получите помощь от сообщества

Почему стоит использовать Instructor, а не альтернативы?

Против сырого JSON-режима: Instructor обеспечивает автоматическую валидацию, повторные попытки, потоковую передачу и поддержку вложенных объектов. Никакого ручного написания схем.

Против LangChain/LlamaIndex: Instructor сосредоточен на одной вещи — структурированном извлечении. Он легче, быстрее и проще для отладки.

Против пользовательских решений: Проверено тысячами разработчиков. Обрабатывает пограничные случаи, о которых вы даже не думали.

Участие в разработке

Мы приветствуем вклад! Ознакомьтесь с нашими задачами для начинающих, чтобы начать.

Лицензия

Лицензия MIT — подробности смотрите в LICENSE.

Построено сообществом Instructor. Особая благодарность Джейсону Лю и всем контрибьюторам.