{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

phác thảo

Đề cương: tạo JSON/regex/Pydantic LLM có cấu trúc.

Siêu dữ liệu kỹ năng


Nguồn	Tùy chọn — cài đặt với
`Hermes skills install official/mlops/outlines
`
Đường dẫn

optional-skills/mlops/inference/outlines ` | | Phiên bản |

outlines

, `transformers

, `vLLM

Prompt Engineering

, `Outlines

, `Structured Generation

, `JSON Schema

, `Pydantic

, `Local Models

, `Grammar-Based Generation

, `vLLM

, `Transformers

, Type Safety |

Tham khảo: đầy đủ SKILL.md

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

Dàn ý: Tạo văn bản có cấu trúc

Khi nào nên sử dụng kỹ năng này

Sử dụng Dàn bài khi bạn cần:

Đảm bảo cấu trúc JSON/XML/mã hợp lệ trong quá trình tạo
Sử dụng mô hình Pydantic cho đầu ra an toàn kiểu
Hỗ trợ các mô hình địa phương (Transformers, Llama.cpp, vLLM)
Tối đa hóa tốc độ suy luận với thế hệ có cấu trúc không cần chi phí
Tự động tạo dựa trên các lược đồ JSON
Lấy mẫu mã thông báo kiểm soát ở cấp độ ngữ pháp`Sao GitHub: 8.000+ | Từ: dottxt.ai (trước đây là .txt)

Cài đặt

# Base installation
pip install outlines

# With specific backends
pip install outlines transformers  # Hugging Face models
pip install outlines Llama-cpp-Python  # Llama.cpp
pip install outlines vLLM  # vLLM for high-throughput

`

## Bắt đầu nhanh

### Ví dụ cơ bản: Phân loại

``` python
 import outlines
from typing import Literal

# Load model
model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")

# Generate with type constraint
prompt = "Sentiment of 'This product is amazing!': "
generator = outlines.generate.choice(model, ["positive", "negative", "neutral"])
sentiment = generator(prompt)

print(sentiment)  # "positive" (guaranteed one of these)

`

### Với mô hình Pydantic

`Python
from pydantic import BaseModel
 import outlines`class User(BaseModel):
    name: str
    age: int
    email: str`model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")

# Generate structured output
prompt = "Extract user: John Doe, 30 years old, john@example.com"
generator = outlines.generate.JSON(model, User)
user = generator(prompt)

print(user.name)   # "John Doe"
print(user.age)    # 30
print(user.email)  # "john@example.com"

`

## Khái niệm cốt lõi

### 1. Lấy mẫu mã thông báo bị ràng buộc

Outlines sử dụng Máy trạng thái hữu hạn (FSM) để hạn chế việc tạo mã thông báo ở cấp logit.

**Cách thức hoạt động:**

1. Chuyển đổi lược đồ (JSON/Pydantic/regex) sang ngữ pháp phi ngữ cảnh (CFG)
2. Chuyển đổi CFG thành Máy trạng thái hữu hạn (FSM)
3. Lọc mã thông báo không hợp lệ ở mỗi bước trong quá trình tạo
4. Chuyển tiếp nhanh khi chỉ tồn tại một mã thông báo hợp lệ`**Quyền lợi:**
- **Không có chi phí**: Quá trình lọc diễn ra ở cấp mã thông báo
- **Cải thiện tốc độ**: Chuyển tiếp nhanh qua các đường dẫn xác định
- **Đảm bảo tính hợp lệ**: Không thể có kết quả đầu ra không hợp lệ

``` python
 import outlines

# Pydantic model -> JSON schema -> CFG -> FSM
class Person(BaseModel):
    name: str
    age: int`model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")

# Behind the scenes:

# 1. Person -> JSON schema
# 2. JSON schema -> CFG
# 3. CFG -> FSM
# 4. FSM filters tokens during generation`generator = outlines.generate.JSON(model, Person)
result = generator("Generate person: Alice, 25")

`

### 2. Trình tạo cấu trúc

Outlines cung cấp các trình tạo chuyên dụng cho các loại đầu ra khác nhau.

#### Trình tạo lựa chọn

``` python

# Multiple choice selection
generator = outlines.generate.choice(
    model,
    ["positive", "negative", "neutral"]
)

sentiment = generator("Review: This is great!")
# Result: One of the three choices

`

#### Trình tạo JSON

``` python
from pydantic import BaseModel`class Product(BaseModel):
    name: str
    price: float
    in_stock: bool

# Generate valid JSON matching schema
generator = outlines.generate.JSON(model, Product)
product = generator("Extract: iPhone 15, $999, available")

# Guaranteed valid Product instance
print(type(product))  # &lt;class '__main__.Product'

`

#### Trình tạo Regex

`Python

# Generate text matching regex
generator = outlines.generate.regex(
    model,
    r"[0-9]\\&#123;3&#125;-[0-9]\\&#123;3&#125;-[0-9]\\&#123;4&#125;"  # Phone number pattern
)

phone = generator("Generate phone number:")
# Result: "555-123-4567" (guaranteed to match pattern)

`

#### Bộ tạo số nguyên/số float

``` python

# Generate specific numeric types
int_generator = outlines.generate.integer(model)
age = int_generator("Person's age:")  # Guaranteed integer`float_generator = outlines.generate.float(model)
price = float_generator("Product price:")  # Guaranteed float

`

### 3. Phần cuối của mô hình

Outlines hỗ trợ nhiều chương trình phụ trợ cục bộ và dựa trên API.

#### Transformers (Hugging Face)

``` python
 import outlines

# Load from Hugging Face
model = outlines.models.transformers(
    "Microsoft/Phi-3-mini-4k-instruct",
    device="cuda"  # Or "cpu"
)

# Use with any generator
generator = outlines.generate.JSON(model, YourModel)

`

#### Llama.cpp

`Python

# Load GGUF model
model = outlines.models.LlamACPp(
    "./models/Llama-3.1-8b-instruct.Q4_K_M.gguf",
    n_gpu_layers=35
)

generator = outlines.generate.JSON(model, YourModel)

`

#### vLLM (Thông lượng cao)

``` python

# For production deployments
model = outlines.models.vLLM(
    "meta-Llama/Llama-3.1-8B-Instruct",
    tensor_parallel_size=2  # Multi-GPU
)

generator = outlines.generate.JSON(model, YourModel)

`

#### OpenAI (Hỗ trợ có giới hạn)

``` python

# Basic OpenAI support
model = outlines.models.OpenAI(
    "GPT-4o-mini",
    API_key="your-API-key"
)

# Note: Some features limited with API models
generator = outlines.generate.JSON(model, YourModel)

`

### 4. Tích hợp Pydantic

Outlines có hỗ trợ Pydantic hạng nhất với tính năng dịch lược đồ tự động.`####Mô hình cơ bản

``` python
from pydantic import BaseModel, Field`class Article(BaseModel):
    title: str = Field(description="Article title")
    author: str = Field(description="Author name")
    word_count: int = Field(description="Number of words", gt=0)
    tags: list[str] = Field(description="List of tags")

model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")
generator = outlines.generate.JSON(model, Article)

article = generator("Generate article about AI")
print(article.title)
print(article.word_count)  # Guaranteed > 0

`

#### Mô hình lồng nhau

`Python
class Address(BaseModel):
    street: str
    city: str
    country: str`class Person(BaseModel):
    name: str
    age: int
    address: Address  # Nested model`generator = outlines.generate.JSON(model, Person)
person = generator("Generate person in New York")

print(person.address.city)  # "New York"

`

#### Enum và Literal

`Python
from enum import Enum
from typing import Literal`class Status(str, Enum):
    PENDING = "pending"
    APPROVED = "approved"
    REJECTED = "rejected"`class Application(BaseModel):
    applicant: str
    status: Status  # Must be one of enum values
    priority: Literal["low", "medium", "high"]  # Must be one of literals`generator = outlines.generate.JSON(model, Application)
app = generator("Generate application")

print(app.status)  # Status.PENDING (or APPROVED/REJECTED)

`

## Các mẫu phổ biến

### Mẫu 1: Trích xuất dữ liệu

`Python
from pydantic import BaseModel
 import outlines`class CompanyInfo(BaseModel):
    name: str
    founded_year: int
    industry: str
    employees: int`model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")
generator = outlines.generate.JSON(model, CompanyInfo)

text = """
Apple Inc. was founded in 1976 in the technology industry.
The company employs approximately 164,000 people worldwide.
"""`prompt = f"Extract company information:\n\&#123;text&#125;\n\nCompany:"
company = generator(prompt)

print(f"Name: \&#123;company.name&#125;")
print(f"Founded: \&#123;company.founded_year&#125;")
print(f"Industry: \&#123;company.industry&#125;")
print(f"Employees: \&#123;company.employees&#125;")

`

### Mẫu 2: Phân loại

`Python
from typing import Literal
 import outlines`model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")

# Binary classification
generator = outlines.generate.choice(model, ["spam", "not_spam"])
result = generator("Email: Buy now! 50% off!")

# Multi-class classification
categories = ["technology", "business", "sports", "entertainment"]
category_gen = outlines.generate.choice(model, categories)
category = category_gen("Article: Apple announces new iPhone...")

# With confidence
class Classification(BaseModel):
    label: Literal["positive", "negative", "neutral"]
    confidence: float`classifier = outlines.generate.JSON(model, Classification)
result = classifier("Review: This product is okay, nothing special")

`

### Mẫu 3: Biểu mẫu có cấu trúc

`Python
class UserProfile(BaseModel):
    full_name: str
    age: int
    email: str
    phone: str
    country: str
    interests: list[str]

model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")
generator = outlines.generate.JSON(model, UserProfile)

prompt = """
Extract user profile from:
Name: Alice Johnson
Age: 28
Email: alice@example.com
Phone: 555-0123
Country: USA
Interests: hiking, photography, cooking
"""`profile = generator(prompt)
print(profile.full_name)
print(profile.interests)  # ["hiking", "photography", "cooking"]

`

### Mẫu 4: Trích xuất đa thực thể

`Python
class Entity(BaseModel):
    name: str
    type: Literal["PERSON", "ORGANIZATION", "LOCATION"]

class DocumentEntities(BaseModel):
    entities: list[Entity]

model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")
generator = outlines.generate.JSON(model, DocumentEntities)

text = "Tim Cook met with Satya Nadella at Microsoft headquarters in Redmond."
prompt = f"Extract entities from: \&#123;text&#125;"`result = generator(prompt)
for entity in result.entities:
    print(f"\&#123;entity.name&#125; (\&#123;entity.type&#125;)")

`

### Mẫu 5: Tạo mã

`Python
class PythonFunction(BaseModel):
    function_name: str
    parameters: list[str]
    docstring: str
    body: str`model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")
generator = outlines.generate.JSON(model, PythonFunction)

prompt = "Generate a Python function to calculate factorial"
func = generator(prompt)

print(f"def \&#123;func.function_name&#125;(\&#123;', '.join(func.parameters)&#125;):")
print(f'    """\&#123;func.docstring&#125;"""')
print(f"    \&#123;func.body&#125;")

`

### Mẫu 6: Xử lý hàng loạt

`Python
def batch_extract(texts: list[str], schema: type[BaseModel]):
    """Extract structured data from multiple texts."""
    model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")
    generator = outlines.generate.JSON(model, schema)

results = []
    for text in texts:
        result = generator(f"Extract from: \&#123;text&#125;")
        results.append(result)

return results`class Person(BaseModel):
    name: str
    age: int`texts = [
    "John is 30 years old",
    "Alice is 25 years old",
    "Bob is 40 years old"
]

people = batch_extract(texts, Person)
for person in people:
    print(f"\&#123;person.name&#125;: \&#123;person.age&#125;")

`

## Cấu hình phụ trợ

### Máy biến áp

`Python
 import outlines

# Basic usage
model = outlines.models.transformers("Microsoft/Phi-3-mini-4k-instruct")

# GPU configuration
model = outlines.models.transformers(
    "Microsoft/Phi-3-mini-4k-instruct",
    device="cuda",
    model_kwargs=\&#123;"torch_dtype": "float16"&#125;
)

# Popular models
model = outlines.models.transformers("meta-Llama/Llama-3.1-8B-Instruct")
model = outlines.models.transformers("Mistralai/Mistral-7B-Instruct-v0.3")
model = outlines.models.transformers("Qwen/Qwen2.5-7B-Instruct")

`

### Llama.cpp

`Python

# Load GGUF model
model = outlines.models.LlamACPp(
    "./models/Llama-3.1-8b.Q4_K_M.gguf",
    n_ctx=4096,         # Context window
    n_gpu_layers=35,    # GPU layers
    n_threads=8         # CPU threads
)

# Full GPU offload
model = outlines.models.LlamACPp(
    "./models/model.gguf",
    n_gpu_layers=-1  # All layers on GPU
)

`

### vLLM (Sản xuất)

``` python

# Single GPU
model = outlines.models.vLLM("meta-Llama/Llama-3.1-8B-Instruct")

# Multi-GPU
model = outlines.models.vLLM(
    "meta-Llama/Llama-3.1-70B-Instruct",
    tensor_parallel_size=4  # 4 GPUs
)

# With quantization
model = outlines.models.vLLM(
    "meta-Llama/Llama-3.1-8B-Instruct",
    quantization="awq"  # Or "GPTq"
)

`

## Các phương pháp hay nhất

### 1. Sử dụng các loại cụ thể

``` python

# ✅ Good: Specific types
class Product(BaseModel):
    name: str
    price: float  # Not str
    quantity: int  # Not str
    in_stock: bool  # Not str

# ❌ Bad: Everything as string
class Product(BaseModel):
    name: str
    price: str  # Should be float
    quantity: str  # Should be int

`

### 2. Thêm ràng buộc

``` python
from pydantic import Field

# ✅ Good: With constraints
class User(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    age: int = Field(ge=0, le=120)
    email: str = Field(pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$")

# ❌ Bad: No constraints
class User(BaseModel):
    name: str
    age: int
    email: str

`

### 3. Sử dụng Enums cho Danh mục

`Python

# ✅ Good: Enum for fixed set
class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"`class Task(BaseModel):
    title: str
    priority: Priority

# ❌ Bad: Free-form string
class Task(BaseModel):
    title: str
    priority: str  # Can be anything

`

### 4. Cung cấp ngữ cảnh trong lời nhắc

``` python

# ✅ Good: Clear context
prompt = """
Extract product information from the following text.
Text: iPhone 15 Pro costs $999 and is currently in stock.
Product:
"""

# ❌ Bad: Minimal context
prompt = "iPhone 15 Pro costs $999 and is currently in stock."

`

### 5. Xử lý các trường tùy chọn

``` python
from typing import Optional

# ✅ Good: Optional fields for incomplete data
class Article(BaseModel):
    title: str  # Required
    author: Optional[str] = None  # Optional
    date: Optional[str] = None  # Optional
    tags: list[str] = []  # Default empty list

# Can succeed even if author/date missing

`

## So sánh với các lựa chọn thay thế

| Tính năng | Đề cương | Giảng viên | Hướng dẫn | LMQL |
|----------|----------|-------------|----------|------|
| Hỗ trợ Pydantic | ✅ Bản địa | ✅ Bản địa | ❌ Không | ❌ Không |
| Lược đồ JSON | ✅ Có | ✅ Có | ⚠️ Có hạn | ✅ Có |
| Ràng buộc Regex | ✅ Có | ❌ Không | ✅ Có | ✅ Có |
| Mô hình địa phương | ✅ Đầy đủ | ⚠️ Có hạn | ✅ Đầy đủ | ✅ Đầy đủ |
| Mô hình API | ⚠️ Có hạn | ✅ Đầy đủ | ✅ Đầy đủ | ✅ Đầy đủ |
| Không có chi phí | ✅ Có | ❌ Không | ⚠️ Một phần | ✅ Có |
| Tự động thử lại | ❌ Không | ✅ Có | ❌ Không | ❌ Không |
| Đường cong học tập | Thấp | Thấp | Thấp | Cao |**Khi nào nên chọn Đường viền:**

- Sử dụng các mô hình cục bộ (Transformers, Llama.cpp, vLLM)
- Cần tốc độ suy luận tối đa
- Muốn hỗ trợ mô hình Pydantic
- Yêu cầu tạo cấu trúc không chi phí
- Kiểm soát quá trình lấy mẫu mã thông báo`**Khi nào nên chọn phương án thay thế:**
- Người hướng dẫn: Cần mô hình API có tính năng tự động thử lại
- Hướng dẫn: Cần chữa lành mã thông báo và quy trình làm việc phức tạp
- LMQL: Ưu tiên cú pháp truy vấn khai báo

## Đặc tính hiệu suất`**Tốc độ:**
- **Không có chi phí**: Tạo cấu trúc nhanh như không bị giới hạn
- **Tối ưu hóa chuyển tiếp nhanh**: Bỏ qua các mã thông báo xác định
- **Nhanh hơn 1,2-2 lần** so với các phương pháp xác thực sau thế hệ`**Bộ nhớ:**
- FSM được biên dịch một lần trên mỗi lược đồ (được lưu trong bộ nhớ cache)
- Chi phí thời gian chạy tối thiểu
- Hiệu quả với vLLM cho thông lượng cao`**Độ chính xác:**
- **100% đầu ra hợp lệ** (được FSM đảm bảo)
- Không cần vòng thử lại
- Lọc mã thông báo xác định

## Tài nguyên
- **Tài liệu**: https://outlines-dev.GitHub.io/outlines
- **GitHub**: https://GitHub.com/outlines-dev/outlines (8k+ sao)
- **Discord**: https://Discord.gg/R9DSu34mGd
- **Blog**: https://blog.dottxt.co

## Xem thêm
- 
`references/JSON_generation.md

 - Các mẫu JSON và Pydantic toàn diện
- 
`references/backends.md

 - Cấu hình dành riêng cho phần phụ trợ
- 
`references/examples.md

 - Ví dụ sẵn sàng sản xuất

Siêu dữ liệu kỹ năng​

Tham khảo: đầy đủ SKILL.md​

Dàn ý: Tạo văn bản có cấu trúc

Khi nào nên sử dụng kỹ năng này​

Cài đặt​

Siêu dữ liệu kỹ năng

Tham khảo: đầy đủ SKILL.md

Khi nào nên sử dụng kỹ năng này

Cài đặt