# https://github.com/dottxt-ai/outlines 项目说明书 生成时间: 2026-05-21 17:17:18 UTC ## 目录 - [Outlines 简介](#page-introduction) - [安装指南](#page-installation) - [快速开始](#page-quickstart) - [系统架构](#page-architecture) - [核心概念](#page-core-concepts) - [输出类型](#page-output-types) - [类型系统](#page-type-system) - [模型提供者](#page-model-providers) - [生成器系统](#page-generator) - [后端系统](#page-backends) ## Outlines 简介 ### 相关页面 相关主题：[安装指南](#page-installation), [系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) - [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) - [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py) - [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) - [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)
# Outlines 简介 ## 项目概述 Outlines 是一个用于引导大语言模型（LLM）生成结构化输出的开源框架。该项目由 .txt 团队开发和维护，旨在解决 LLM 输出不确定性这一核心问题。 传统的 LLM 应用通常在生成后通过解析、正则表达式或脆弱的解析代码来尝试修复不良输出，这种方式容易出错且难以维护。Outlines 采用不同的方法：在生成过程中直接确保输出结构符合预期，从而从根本上保证输出的有效性。 **核心价值主张：** - **结构保证**：在生成过程中直接约束输出格式，而非事后解析 - **模型无关性**：同一套代码可在 OpenAI、Ollama、vLLM 等多种模型上运行 - **类型安全**：通过 Python 类型系统直接指定输出类型 - **提供商独立性**：切换模型时无需修改业务代码 资料来源：[README.md:1-30]() ## 核心特性 ### 支持的模型提供商 Outlines 支持多种模型集成方式，形成统一的抽象接口： | 提供商类型 | 具体实现 | 异步支持 | |-----------|---------|---------| | 本地模型 | Transformers、VLLM、LlamaCpp、Ollama | 是 | | OpenAI 系列 | OpenAI、Azure OpenAI | 是 | | Anthropic 系列 | Claude 模型 | 是 | | Google 系列 | Gemini | 是 | | 其他 | SGLang、TGI、Transformers.js | 是 | 异步模型包括 `AsyncSGLang`、`AsyncTGI`、`AsyncVLLM` 等，可通过以下方式初始化： ```python import outlines from huggingface_hub import AsyncInferenceClient async_model = outlines.from_tgi(AsyncInferenceClient("http://localhost:11434")) ``` 资料来源：[README.md:60-80]() ### 输出类型系统 Outlines 的核心设计理念是让用户通过 Python 类型系统直接指定期望的输出结构： | 输出类型 | 定义方式 | 示例 | |---------|---------|-----| | 字面量类型 | `Literal` | `Literal["Yes", "No"]` | | 数值类型 | Python 内置类型 | `int`、`float` | | 列表类型 | `list[T]` | `list[str]` | | 复杂对象 | Pydantic 模型 | `BaseModel` 子类 | | 正则约束 | Regex DSL | `Regex`、`String` | | JSON Schema | `JsonSchema` | `JsonSchema(schema_str)` | | 上下文无关文法 | `CFG` | CFG 语法定义 | ```python from pydantic import BaseModel from typing import Literal class ProductReview(BaseModel): rating: Literal["poor", "fair", "good", "excellent"] pros: list[str] cons: list[str] summary: str ``` 资料来源：[outlines/release_note.md:30-60]() ### 架构设计 Outlines 采用分层架构设计，核心组件关系如下： ```mermaid graph TD A[用户代码] --> B[模型调用层] B --> C[Generator 生成器] C --> D[输出类型编译] D --> E[Logits Processor] E --> F[底层模型推理] G[Transformers] --> F H[VLLM] --> F I[OpenAI] --> F J[Anthropic] --> F K[BaseModel] --> D L[Literal Type] --> D M[Regex DSL] --> D ``` #### 模型基类设计 所有模型类继承自 `BaseModel`（异步）或 `BaseModel` 的变体，提供统一的调用接口： ```mermaid graph LR A[__call__] --> B[创建 Generator] C[batch] --> B D[stream] --> B B --> E[执行生成] F[type_adapter] -.-> A G[tensor_library_name] -.-> F ``` 模型类必须定义 `type_adapter` 属性（类型 `ModelTypeAdapter`）和 `tensor_library_name` 属性。 资料来源：[outlines/models/base.py:1-50]() ## 快速开始指南 ### 安装 ```shell pip install outlines ``` 资料来源：[README.md:35-40]() ### 基本使用流程 ```mermaid graph LR A[安装 Outlines] --> B[加载模型] B --> C[定义输出类型] C --> D[调用模型生成] D --> E[获取结构化输出] ``` ### 第一步：连接模型 ```python import outlines from transformers import AutoTokenizer, AutoModelForCausalLM MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct" model = outlines.from_transformers( AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"), AutoTokenizer.from_pretrained(MODEL_NAME) ) ``` 资料来源：[README.md:42-55]() ### 第二步：简单分类任务 ```python from typing import Literal sentiment = model( "Analyze: 'This product completely changed my life!'", Literal["Positive", "Negative", "Neutral"] ) print(sentiment) # "Positive" ``` 资料来源：[README.md:56-65]() ### 第三步：数值提取 ```python temperature = model("What's the boiling point of water in Celsius?", int) print(temperature) # 100 ``` 资料来源：[README.md:66-70]() ### 第四步：复杂结构 ```python from pydantic import BaseModel from enum import Enum class Rating(Enum): poor = 1 fair = 2 good = 3 excellent = 4 class ProductReview(BaseModel): rating: Rating pros: list[str] cons: list[str] review = model( "Write a review for the iPhone 15 Pro", ProductReview ) ``` 资料来源：[README.md:71-90]() ## Generator 生成器 Generator 是 Outlines v1 版本引入的核心组件，用于封装模型和输出类型的组合。 ### 设计目的 Generator 的主要价值在于**可重用性**和**编译缓存**： | 特性 | 说明 | |-----|------| | 可重用性 | 无需每次调用时指定输出类型 | | 编译缓存 | 输出类型的编译（当适用时）仅执行一次 | | 批处理支持 | 同一 Generator 可处理多个输入 | ### 基本用法 ```python from outlines import Generator, from_transformers from pydantic import BaseModel class Character(BaseModel): name: str age: int model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) # 创建 Generator generator = Generator(model, Character) # 多次调用，输出类型无需重复指定 result1 = generator("Create a young wizard character") result2 = generator("Create an old warrior character") ``` ### Generator 方法 | 方法 | 描述 | 异步版本 | |-----|------|---------| | `__call__` | 单次生成 | `async def __call__` | | `batch` | 批量生成 | `async def batch` | | `stream` | 流式生成 | `async def stream` | 资料来源：[outlines/models/base.py:50-120]() ## 正则表达式 DSL Outlines 提供了正则表达式领域特定语言（Regex DSL），允许通过代码组合构建复杂的正则模式。 ### 可用组件 | 组件 | 功能 | 示例 | |-----|------|-----| | `Regex` | 匹配正则表达式 | `Regex(r"[0-9]+")` | | `String` | 匹配字符串字面量 | `String("yes")` | | `either` | 或运算 | `either(a, b)` | | `optional` | 可选修饰 | `optional(pattern)` | | `at_least` | 至少重复次数 | `at_least(n, pattern)` | | `integer` | 匹配整数 | `integer()` | ### 使用示例 ```python from outlines.types import at_least, either, integer, optional # 构建复杂模式 pattern = either( integer(), at_least(2, String("ab")) ) ``` ### JsonSchema 类型 `JsonSchema` 是一个独立的 Term，可直接用作输出类型： ```python from outlines.types import JsonSchema json_schema = '{"type": "object", "properties": {"answer": {"type": "number"}}}' result = model("What's 2 + 2? Respond in a json", JsonSchema(json_schema)) ``` 资料来源：[outlines/release_note.md:60-90]() ## 异常处理体系 Outlines 定义了完整的异常层次结构，便于应用程序进行错误处理。 ### 异常层次 ```mermaid graph TD A[Exception] --> B[OutlinesError] B --> C[APIError] C --> D[AuthenticationError] C --> E[PermissionDeniedError] C --> F[NotFoundError] C --> G[RateLimitError] C --> H[BadRequestError] C --> I[ServerError] C --> J[APITimeoutError] C --> K[APIConnectionError] B --> L[ProviderResponseError] B --> M[GenerationError] ``` ### APIError 核心属性 | 属性 | 类型 | 说明 | |-----|------|------| | `provider` | `str \| None` | 提供商名称，如 `"openai"` | | `original_exception` | `Exception \| None` | 原始 SDK 异常 | | `status_code` | `int \| None` | HTTP 状态码 | | `request_id` | `str \| None` | 提供商请求 ID | | `retryable` | `bool` | 是否可重试 | | `hint` | `str` | 人类可读的建议信息 | ### 错误处理示例 ```python from outlines.exceptions import APIError, RateLimitError, normalize_provider_errors try: with normalize_provider_errors(provider="openai"): result = model("Generate something", str) except RateLimitError as e: print(f"Rate limited: {e.hint}") except APIError as e: print(f"API Error: {e.request_id}") ``` 资料来源：[outlines/exceptions.py:1-60]() ## 版本迁移指南 ### v0 到 v1 重要变更 #### 移除的功能 | 旧功能 | 替代方案 | 说明 | |-------|---------|------| | `Function` 类 | `Application` 类 | Application 不在初始化时绑定模型 | | `Template.from_file` | `Template.from_string` + 文件读取 | 简化模板加载逻辑 | | Exllamav2 模型 | 无替代 | 接口不兼容，已移除 | | `load_lora` 方法 | LoRA 请求参数 | 通过 `lora_request` 参数传递 | #### Function 到 Application 迁移 ```python # v0 写法（已废弃） from outlines import Function, Template class Character(BaseModel): name: str template = Template.from_string("Create a {{ gender }} character.") fn = Function(template, Character, "hf-internal-testing/tiny-random-GPTJForCausalLM") response = fn(gender="female") # v1 写法（推荐） from outlines import Application, Template template = Template.from_string("Create a {{ gender }} character.") app = Application(template, Character) response = app(model, {"gender": "female"}) ``` #### LoRA 加载变更 ```python # v0 写法（已废弃） model.load_lora("path/to/lora/file") # v1 写法（推荐） from vllm.lora.request import LoRARequest lora_request = LoRARequest("my_lora", 1, "path/to/lora/file") response = model("Write a short story", str, lora_request=lora_request) ``` 资料来源：[outlines/release_note.md:1-40]() ### 模型调用方式变化 v1 版本支持直接调用模型，无需先创建生成器： ```python # 方式一：直接调用（v1 新增） result = model("Write a story", str, max_tokens=100) # 方式二：使用 Generator（v1 新增） generator = Generator(model, str) result = generator("Write a story", max_tokens=100) ``` 两种方式等效，Generator 的优势在于可重用性和编译缓存。 资料来源：[outlines/release_note.md:100-120]() ## 应用示例 ### 客户服务工单分类 ```python from pydantic import BaseModel from typing import Literal class ServiceTicket(BaseModel): category: Literal["billing", "technical", "shipping", "general"] priority: Literal["low", "medium", "high", "urgent"] summary: str requires_manager: bool ticket = model(prompt, ServiceTicket, max_new_tokens=500) # 根据结果路由 if ticket.priority == "urgent" or ticket.requires_manager: alert_manager(ticket) ``` ### 产品分类 ```python from pydantic import BaseModel from typing import List, Optional class ProductCategory(BaseModel): main_category: str sub_category: str attributes: List[str] brand_match: Optional[str] # 处理产品描述 product = "Apple iPhone 15 Pro, 256GB, Titanium Gray" result = model(product, ProductCategory) ``` ### 会议安排 ```python from typing import List, Optional from datetime import date def schedule_meeting( title: str, date: date, duration_minutes: int, attendees: List[str], location: Optional[str] = None, agenda_items: Optional[List[str]] = None ): # 实际应用中创建会议 meeting = { "title": title, "date": date, "duration_minutes": duration_minutes, "attendees": attendees, } return f"Meeting '{title}' scheduled" result = model(natural_language_request, schedule_meeting) ``` 资料来源：[README.md:100-180]() ## 部署选项 ### Modal 部署 Outlines 支持在 Modal 平台上部署： ```python import modal app = modal.App(name="outlines-app") outlines_image = modal.Image.debian_slim(python_version="3.11").pip_install( "outlines==1.0.0", "transformers==4.38.2", "datasets==2.18.0", "accelerate==0.27.2", ) ``` 资料来源：[examples/modal_example.py:1-20]() ### BentoML 部署 ```python # requirements.txt bentoml>=1.2.11 outlines==0.0.37 transformers==4.38.2 datasets==2.18.0 accelerate==0.27.2 ``` 资料来源：[examples/bentoml/requirements.txt:1-5]() ## 核心设计原则 Outlines 的设计遵循以下原则： | 原则 | 描述 | 实现方式 | |-----|------|---------| | 类型即约束 | 期望输出通过类型指定 | Pydantic、Literal、int 等 | | 生成时验证 | 结构在生成过程中保证 | Logits Processor | | 模型抽象 | 统一接口支持多模型 | BaseModel 基类 | | 异步优先 | 完整异步支持 | AsyncModel 基类 | | 渐进式复杂度 | 从简单到复杂逐步深入 | 多种输出类型选项 | **类型即约束**的设计哲学与 Python 自身的类型系统保持一致，使得开发者可以像定义函数返回类型一样定义 LLM 输出的期望结构。 资料来源：[README.md:20-35]() ## 总结 Outlines 是一个功能强大且设计优雅的结构化输出框架，通过以下核心能力解决了 LLM 应用开发中的关键挑战： 1. **生成时结构保证**：避免生成后解析的不确定性和脆弱性 2. **统一的模型接口**：支持多种提供商，切换模型无需修改业务代码 3. **Pythonic 类型系统**：利用 Python 原生类型指定输出结构 4. **灵活的输出约束**：支持 Literal、Pydantic、Regex、JSON Schema 等多种约束方式 5. **完整的异步支持**：适配现代异步应用架构 6. **清晰的异常层次**：便于错误处理和调试 Outlines v1 版本通过引入 Generator 组件、异步模型支持和完善的类型系统，进一步提升了框架的可用性和灵活性，使其成为构建生产级 LLM 应用的理想选择。 --- ## 安装指南 ### 相关页面 相关主题：[Outlines 简介](#page-introduction), [快速开始](#page-quickstart)
相关源码文件 以下源码文件用于生成本页说明： - [pyproject.toml](https://github.com/dottxt-ai/outlines/blob/main/pyproject.toml) - [environment.yml](https://github.com/dottxt-ai/outlines/blob/main/environment.yml) - [examples/bentoml/requirements.txt](https://github.com/dottxt-ai/outlines/blob/main/examples/bentoml/requirements.txt) - [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py) - [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)
# 安装指南 ## 概述 Outlines 是一个用于大语言模型（LLM）结构化输出的 Python 库。本指南将帮助用户在各种环境中正确安装和配置 Outlines。 ## 系统要求 ### Python 版本 Outlines 需要 Python 3.10 或更高版本。 ```资料来源：[examples/modal_example.py:1]()[examples/bentoml/requirements.txt:4]() 依赖项版本兼容性： - Python ≥ 3.10 - outlines ≥ 1.0.0 ``` ## 安装方法 ### 使用 pip 安装（推荐） 通过 pip 安装 Outlines 是最简单的方式： ```bash pip install outlines ``` 资料来源：[README.md:1]() ### 从源码安装 对于需要最新功能或想要参与开发的用户，可以从源码安装： ```bash git clone https://github.com/dottxt-ai/outlines.git cd outlines pip install -e . ``` ## 核心依赖 Outlines 的核心功能依赖于以下库： | 依赖项 | 用途 | 最低版本 | |--------|------|----------| | pydantic | 数据验证和结构定义 | - | | interegular | 正则表达式处理和 FSM 编译 | - | | numpy | 数值计算支持 | - | 资料来源：[pyproject.toml](https://github.com/dottxt-ai/outlines/blob/main/pyproject.toml) ## 模型后端安装 Outlines 支持多种模型后端，不同的后端需要不同的依赖配置。 ### Transformers 后端 用于本地 Hugging Face 模型，需要安装 transformers 和相关依赖： ```资料来源：[README.md:1]() ```python import outlines from transformers import AutoTokenizer, AutoModelForCausalLM MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct" model = outlines.from_transformers( AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"), AutoTokenizer.from_pretrained(MODEL_NAME) ) ``` 依赖版本要求： ``` transformers>=4.38.2 datasets>=2.18.0 accelerate>=0.27.2 ``` 资料来源：[examples/bentoml/requirements.txt:3-5]() ### vLLM 后端 用于高效的推理服务部署： ```python from outlines import from_vllm from vllm import LLM model = from_vllm(LLM("microsoft/Phi-3-mini-4k-instruct")) ``` 安装 vLLM 后端需要单独的 vLLM 库： ```bash pip install vllm ``` ### OpenAI API 后端 用于调用 OpenAI API 模型： ```python import outlines model = outlines.openai("gpt-4") result = model("Hello world", str) ``` ### Anthropic API 后端 用于调用 Anthropic Claude 模型： ```python import outlines model = outlines.anthropic("claude-3-opus-20240229") result = model("Hello world", str) ``` ### Ollama 后端 用于调用本地 Ollama 模型： ```python from huggingface_hub import AsyncInferenceClient import outlines async_model = outlines.from_tgi(AsyncInferenceClient("http://localhost:11434")) ``` ## 环境配置 ### 使用 conda 环境 可以通过 environment.yml 创建完整的环境： ```yaml name: outlines-env dependencies: - python>=3.10 - pip - pip: - outlines - transformers - accelerate ``` 创建环境命令： ```bash conda env create -f environment.yml conda activate outlines-env ``` 资料来源：[environment.yml](https://github.com/dottxt-ai/outlines/blob/main/environment.yml) ### GPU 环境配置 对于使用 GPU 进行推理的模型，需要配置 CUDA 环境： 1. 确保安装 NVIDIA 驱动 2. 安装对应版本的 CUDA Toolkit 3. 安装 PyTorch with CUDA 支持： ```bash pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 ``` ## Docker 部署 ### 使用 Modal 部署 Outlines 支持通过 Modal 进行云端部署： ```python import modal app = modal.App(name="outlines-app") outlines_image = modal.Image.debian_slim(python_version="3.11").pip_install( "outlines==1.0.0", "transformers==4.38.2", "datasets==2.18.0", "accelerate==0.27.2", ) ``` 资料来源：[examples/modal_example.py:7-12]() ### BentoML 部署 Outlines 也可以通过 BentoML 进行容器化部署： 依赖要求： ``` bentoml>=1.2.11 outlines==0.0.37 transformers==4.38.2 datasets>=2.18.0 accelerate>=0.27.2 ``` 资料来源：[examples/bentoml/requirements.txt:1-5]() ## 安装验证 安装完成后，可以通过以下方式验证： ```python import outlines from outlines import from_transformers from transformers import AutoTokenizer, AutoModelForCausalLM # 验证基本导入 print("Outlines 版本:", outlines.__version__) # 验证模型加载（使用最小模型示例） model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) # 测试结构化输出 from typing import Literal result = model("Pizza or burger?", Literal["pizza", "burger"]) print(f"结果: {result}") ``` ## 常见问题 ### 依赖冲突 如果遇到依赖冲突，建议： 1. 创建独立的虚拟环境 2. 使用 `pip install --upgrade` 更新相关包 3. 检查 Python 版本是否满足要求 ### CUDA 版本不兼容 确保 PyTorch 版本与 CUDA 版本匹配： | CUDA 版本 | PyTorch 最低版本 | |-----------|------------------| | CUDA 11.7 | torch >= 1.13 | | CUDA 11.8 | torch >= 2.0 | | CUDA 12.1 | torch >= 2.1 | ### 模型下载失败 如果模型下载失败，可以： 1. 设置 Hugging Face 镜像源 2. 预先下载模型到本地目录 3. 使用离线模式加载已缓存的模型 ## 版本升级 ### 从旧版本升级 从 v0.x 升级到 v1.x 需要注意以下重大变更： | v0.x 特性 | v1.x 等效 | |-----------|-----------| | `Generator` | `Generator` 或直接调用模型 | | `Function` | `Application` | | `load_lora()` | 通过模型实例或参数传递 | 资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) 升级步骤： ```bash pip install --upgrade outlines ``` ## 安装流程图 ```mermaid graph TD A[开始安装] --> B{选择安装方式} B -->|pip| C[pip install outlines] B -->|conda| D[conda env create] B -->|源码| E[git clone && pip install -e] C --> F{需要模型后端?} D --> F E --> F F -->|Transformers| G[安装 transformers/accelerate] F -->|vLLM| H[安装 vllm] F -->|API| I[安装 openai/anthropic SDK] F -->|无后端| J[仅核心功能] G --> K[验证安装] H --> K I --> K J --> K K --> L{验证成功?} L -->|是| M[安装完成] L -->|否| N[排查问题] N --> K ``` ## 相关文档 - [快速入门指南](README.md) - [模型集成](../features/models) - [核心功能](../features/core/generator) - [结构化输出类型](../features/core/ouput_types) --- ## 快速开始 ### 相关页面 相关主题：[Outlines 简介](#page-introduction), [输出类型](#page-output-types)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) - [release_note.md](https://github.com/dottxt-ai/outlines/blob/main/release_note.md) - [examples/dating_profile.py](https://github.com/dottext-ai/outlines/blob/main/examples/dating_profile.py) - [examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py) - [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)
# 快速开始 Outlines 是一个用于在大型语言模型（LLM）生成过程中保证结构化输出的 Python 库。本页面将指导您从安装到完成第一个结构化生成任务，帮助您快速上手 Outlines 的核心功能。 ## 安装 Outlines ### 使用 pip 安装 通过 pip 安装 Outlines 的稳定版本： ```shell pip install outlines ``` 资料来源：[README.md:1]() ### 安装特定版本（可选） 如需安装特定版本，可以使用版本号： ```shell pip install outlines==1.0.0 ``` 资料来源：[examples/modal_example.py:14]() ## 连接模型 Outlines 支持多种模型后端，包括 Transformers、OpenAI、Anthropic、Ollama、vLLM 等。以下介绍最常用的 Transformers 集成方式。 ### 使用 Transformers 模型 ```python import outlines from transformers import AutoTokenizer, AutoModelForCausalLM MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct" model = outlines.from_transformers( AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"), AutoTokenizer.from_pretrained(MODEL_NAME) ) ``` 资料来源：[README.md:1]() ### 从 v0 到 v1 的 API 变化 在 v1 版本中，模型创建方式发生了重要变化： ```python # v0 方式 from outlines import models model = models.transformers("microsoft/Phi-3-mini-4k-instruct") # v1 方式 from outlines import from_transformers model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) ``` 资料来源：[release_note.md:1]() ## 基本结构化输出 Outlines 的核心理念是直接指定输出类型，系统自动保证生成结果符合该结构。 ### 简单分类任务 使用 `Literal` 类型进行分类： ```python from typing import Literal sentiment = model( "Analyze: 'This product completely changed my life!'", Literal["Positive", "Negative", "Neutral"] ) print(sentiment) # 输出: "Positive" ``` 资料来源：[README.md:1]() ### 数值类型输出 直接指定 Python 内置类型： ```python temperature = model("What's the boiling point of water in Celsius?", int) print(temperature) # 输出: 100 ``` 资料来源：[README.md:1]() ## 使用 Pydantic 模型 对于复杂的数据结构，使用 Pydantic 定义模型： ```python from pydantic import BaseModel from enum import Enum class Rating(Enum): poor = 1 fair = 2 good = 3 excellent = 4 class ProductReview(BaseModel): rating: Rating pros: list[str] cons: list[str] summary: str ``` 资料来源：[README.md:1]() ### 完整示例：约会资料生成 以下是一个完整的结构化输出示例： ```python import outlines from pydantic import BaseModel from typing import Optional, List from enum import Enum class MbtiType(str, Enum): INTJ = "INTJ" INFP = "INFP" ENTP = "ENTP" # ... 其他 MBTI 类型 class HobbyCategory(str, Enum): sports = "sports" arts = "arts" gaming = "gaming" outdoors = "outdoors" music = "music" reading = "reading" cooking = "cooking" travel = "travel" class DatingProfile(BaseModel): name: str age: int gender: str mbti: MbtiType location: str height: int bio: str hobbies: List[HobbyCategory] preferred_gender: str preferred_age_range: str personality_traits: List[str] model = outlines.from_transformers( AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"), AutoTokenizer.from_pretrained(MODEL_NAME) ) profile = model("Create a dating profile for a 28-year-old software engineer in San Francisco", DatingProfile) print(profile) ``` 资料来源：[examples/dating_profile.py:1]() ## 使用模板 Outlines 支持 Jinja 模板，便于动态生成提示词： ```python import outlines # 从字符串创建模板 sentiment_template = outlines.Template.from_string(""" <|im_start|>user Analyze the sentiment of the following {{ content_type }}: {{ text }} Provide your analysis as either "Positive", "Negative", or "Neutral". <|im_end> <|im_start|>assistant """) # 使用模板生成提示词 review = "This restaurant exceeded all my expectations. Fantastic service!" prompt = sentiment_template(content_type="review", text=review) # 使用模板进行结构化生成 result = model(prompt, Literal["Positive", "Negative", "Neutral"]) ``` 资料来源：[README.md:1]() ### 从文件加载模板 ```python # 从文件加载模板 example_template = outlines.Template.from_file("templates/few_shot.txt") ``` 资料来源：[README.md:1]() ## ReAct 模式 Outlines 支持 ReAct（Reasoning + Acting）模式，实现链式推理和工具调用： ```python def search_wikipedia(query: str) -> str: """模拟 Wikipedia 搜索""" # 实际实现中会调用 Wikipedia API return f"Results for: {query}" def add_mode(i: int, mode: str, result: str, prompt: str) -> str: """添加观察结果到提示词""" return prompt + f"\n{i}. {mode}: {result}\n" # 初始化 prompt = "Apple Computers" mode = "Thought" # ReAct 循环 for i in range(3): thought = _generator(prompt, stop=["'"], max_tokens=128) if "Search" in thought: subject = " ".join(thought.split()[:2]) result = search_wikipedia(subject) prompt = add_mode(i=i, mode="Obs", result=result, prompt=prompt) else: break ``` 资料来源：[examples/react.py:1]() ## 生成器模式 使用 `Generator` 类可以创建可重用的生成器，避免重复编译： ```python from outlines import Generator, from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) # 创建生成器 generator = Generator(model, Literal["Positive", "Negative", "Neutral"]) # 多次使用，无需重复指定输出类型 result1 = generator("This movie was amazing!") result2 = generator("The food was terrible.") ``` 资料来源：[release_note.md:1]() ## 完整工作流程图 ```mermaid graph TD A[安装 Outlines] --> B[选择模型后端] B --> C{模型类型} C -->|Transformers| D[使用 from_transformers] C -->|OpenAI| E[使用 from_openai] C -->|vLLM| F[使用 from_vllm] D --> G[定义输出类型] E --> G F --> G G --> H{复杂度} H -->|简单类型| I[使用 Literal 或内置类型] H -->|复杂结构| J[使用 Pydantic 模型] I --> K[调用 model 生成] J --> K K --> L[获得结构化输出] ``` ## 快速参考表 | 场景 | 输出类型 | 示例 | |------|----------|------| | 二分类 | `Literal["Yes", "No"]` | 情感判断 | | 多分类 | `Literal["A", "B", "C"]` | 主题分类 | | 整数 | `int` | 数量提取 | | 浮点数 | `float` | 温度提取 | | 复杂对象 | `BaseModel` | JSON 结构 | ## 常见问题 ### 模型调用方式变化 v1 版本支持直接调用模型，无需先创建生成器： ```python # v1 直接调用 result = model("prompt", output_type) # 或使用生成器（推荐重复使用场景） generator = Generator(model, output_type) result = generator("prompt") ``` ### JSON Schema 支持 可以使用 `JsonSchema` 类型直接指定 JSON Schema： ```python from outlines.types import JsonSchema json_schema = '{"type": "object", "properties": {"answer": {"type": "number"}}}' result = model("What's 2 + 2? Respond in a json", JsonSchema(json_schema)) ``` 资料来源：[release_note.md:1]() ## 下一步 - 阅读[安装指南](./guide/installation.md)了解更详细的安装选项 - 查看[架构文档](./guide/architecture.md)深入了解 Outlines 工作原理 - 探索[功能文档](./features/index.md)学习更多高级用法 --- ## 系统架构 ### 相关页面 相关主题：[核心概念](#page-core-concepts), [后端系统](#page-backends)
相关源码文件 以下源码文件用于生成本页说明： - [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py) - [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py) - [outlines/processors/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/processors/__init__.py) - [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt) - [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) - [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) - [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)
# 系统架构 ## 概述 Outlines 是一个保证大型语言模型（LLM）输出结构化的框架。其核心设计理念是通过类型驱动的 API，让用户在调用模型时直接指定期望的输出类型（如 `Literal["Yes", "No"]`、`int` 或 Pydantic 模型），Outlines 会在生成过程中强制保证输出符合该结构。 该框架的核心价值在于**生成时约束**（而不是生成后解析），这避免了传统方法中依赖正则表达式或脆弱解析逻辑所带来的问题。 资料来源：[README.md]() ## 架构分层 Outlines 采用分层架构设计，各层职责清晰，从用户 API 到底层模型提供者形成单向依赖关系： ```mermaid graph TD A[用户 API
outlines.models] --> B[生成器类
SteerableGenerator
BlackBoxGenerator] B --> C[类型系统
types/dsl.py
Pydantic → JsonSchema → Regex] C --> D[FSM 编译
outlines-core
regex → FSM via interegular] D --> E[引导系统
processors/guide.py
FSM 状态管理] E --> F[Logits 处理
processors/structured.py
Token 掩码] F --> G[模型提供者
transformers
OpenAI
vLLM
Ollama] ``` 资料来源：[llm.txt]() ### 层级职责说明 | 层级 | 组件 | 职责 | |------|------|------| | 用户 API | `outlines.models` | 提供统一的模型调用接口 | | 生成器 | `Generator`, `SteerableGenerator`, `BlackBoxGenerator` | 管理生成逻辑和输出类型编译 | | 类型系统 | `types/dsl.py` | 将 Python 类型转换为内部表示 | | FSM 编译 | `outlines-core` | 将正则表达式编译为有限状态机 | | 引导系统 | `processors/guide.py` | 管理 FSM 状态和有效 Token | | Logits 处理 | `processors/structured.py` | 通过 Token 掩码强制约束 | | 模型提供者 | transformers, OpenAI 等 | 与具体模型 API 交互 | 资料来源：[llm.txt]() ## 核心组件 ### 模型层 (`outlines/models/`) #### 模型基类设计 模型层包含两个核心基类，分别对应不同类型的模型： | 基类 | 适用场景 | 控制方式 | |------|----------|----------| | `SteerableModel` | 本地模型（transformers, llama.cpp） | 直接控制 logits | | `BlackBoxModel` | API 模型（OpenAI, Anthropic） | 利用提供商的原生结构化输出支持 | #### 异步支持 v1.0 版本新增了对异步操作的支持，新增了三个异步模型类： - `AsyncSGLang` - `AsyncTGI` - `AsyncVLLM` ```python from outlines import from_tgi from huggingface_hub import AsyncInferenceClient async_model = from_tgi(AsyncInferenceClient("http://localhost:11434")) ``` 资料来源：[outlines/release_note.md]() #### 异步方法接口 所有模型类都实现了以下异步方法： | 方法 | 功能 | 返回类型 | |------|------|----------| | `async stream(...)` | 异步流式生成 | `AsyncIterator[Any]` | | `async batch(...)` | 异步批量生成 | `List[Any]` | | `async __call__(...)` | 异步单次调用 | `Any` | ```python # 流式调用等效方式 generator = Generator(model, Foo) async for chunk in generator("prompt"): print(chunk) # 直接调用模型 async for chunk in model.stream("prompt", Foo): print(chunk) # 等效的异步调用 await model("prompt", Foo) ``` 资料来源：[outlines/models/base.py]() ### 生成器层 #### Generator 类 `Generator` 是 Outlines v1.0 引入的核心组件，用于封装模型和输出类型的组合： ```python from outlines import Generator, from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) generator = Generator(model, int) result = generator("What's 2 + 2?") ``` 生成器的优势在于： - **可复用性**：无需每次调用都指定输出类型 - **延迟编译**：输出类型的 FSM 编译只在首次使用时执行一次 - **持久缓存**：编译结果会被缓存 资料来源：[outlines/release_note.md]() #### 生成器类型 | 类型 | 适用模型 | 约束实现方式 | |------|----------|--------------| | `SteerableGenerator` | 本地模型 | FSM + Logits 掩码 | | `BlackBoxGenerator` | API 模型 | 提供商原生结构化输出 | ### 类型系统 类型系统负责将 Python 类型转换为内部约束表示： ```mermaid graph LR A[Python 类型] --> B[Pydantic 模型] A --> C[Literal 类型] A --> D[JsonSchema] A --> E[Regex/CFG] B --> F[JsonSchema] C --> G[正则表达式] D --> G E --> G F --> H[FSM] G --> H ``` #### 支持的类型格式 | 类型格式 | 示例 | 说明 | |----------|------|------| | `Literal` | `Literal["Yes", "No"]` | 枚举值约束 | | `int` / `float` | `int` | 数值类型约束 | | `Pydantic` | `BaseModel` 子类 | 复杂对象结构 | | `JsonSchema` | `{"type": "object", ...}` | JSON Schema 格式 | | `Regex` | `Regex(r"\d+")` | 正则表达式约束 | | `CFG` | 上下文无关文法 | 形式文法约束 | 资料来源：[outlines/release_note.md]() ### FSM 编译层 FSM（有限状态机）是 Outlines 实现结构化生成的核心机制： ```mermaid graph LR A[正则表达式] -->|interegular| B[FSM] B --> C[状态转换表] C --> D[有效 Token 集合] ``` **工作流程**： 1. 用户指定输出类型（如 `Literal["Yes", "No"]`） 2. 类型系统将其转换为正则表达式 3. 正则表达式通过 `interegular` 库编译为 FSM 4. FSM 在生成过程中追踪有效状态 资料来源：[llm.txt]() ### 引导系统 (`processors/guide.py`) 引导系统负责管理 FSM 状态并计算每个时间步的有效 Token： ```mermaid graph TD A[当前 Token] --> B[FSM 状态更新] B --> C{终止状态?} C -->|是| D[停止生成] C -->|否| E[计算有效 Token] E --> F[掩码 Logits] F --> G[采样下一 Token] G --> A ``` 关键特性： - **Token 级控制**：约束作用于 Token 级别，而非字符级别 - **状态追踪**：维护 FSM 的当前状态 - **动态掩码**：根据有效 Token 集合屏蔽无效 Token 资料来源：[llm.txt]() ### 异常处理 (`outlines/exceptions.py`) Outlines 定义了完整的异常层次结构： ```mermaid graph TD A[Exception] --> B[OutlinesError] B --> C[APIError] C --> D[AuthenticationError] C --> E[PermissionDeniedError] C --> F[NotFoundError] C --> G[RateLimitError] C --> H[BadRequestError] C --> I[ServerError] C --> J[APITimeoutError] C --> K[APIConnectionError] B --> L[ProviderResponseError] B --> M[GenerationError] ``` #### 异常类属性 | 属性 | 类型 | 说明 | |------|------|------| | `provider` | `str \| None` | 提供商名称（如 "openai"） | | `original_exception` | `Exception \| None` | 原始 SDK 异常 | | `status_code` | `int \| None` | HTTP 状态码 | | `request_id` | `str \| None` | 请求 ID（用于问题追踪） | | `retryable` | `bool` | 是否可重试 | | `hint` | `str` | 人类可读的建议信息 | 资料来源：[outlines/exceptions.py]() ## 关键设计决策 ### 1. FSM 基础约束 对于本地模型，约束被编译为有限状态机，用于追踪有效下一个 Token。这种方法确保了生成过程严格遵守结构规范。 资料来源：[llm.txt]() ### 2. 提供商抽象 统一的约束系统同时支持本地模型（transformers）和 API 模型（OpenAI）。对于 API 模型，Outlines 会利用提供商原生的结构化输出功能（如 OpenAI 的 JSON Mode）。 资料来源：[README.md]() ### 3. 延迟编译 FSM 在首次使用时编译并持久缓存，避免了重复编译的开销。 ```python # 首次调用时编译 FSM result = model("What's 2 + 2?", int) # 编译发生在此时 # 后续调用使用缓存 result = model("What's 3 + 3?", int) # 使用缓存的 FSM ``` 资料来源：[outlines/release_note.md]() ### 4. 类型驱动 API Python 类型是指定约束的主要接口，与 Python 自身的类型系统保持一致： | 需求 | 类型指定方式 | |------|--------------| | 是/否回答 | `Literal["Yes", "No"]` | | 数值 | `int` | | 复杂对象 | Pydantic 模型 | 资料来源：[README.md]() ## 模型集成 ### 支持的模型提供商 | 提供商 | 模型类 | 特点 | |--------|--------|------| | Transformers | `Transformers` | 本地模型，完整控制 | | OpenAI | `OpenAI` | API 调用 | | Anthropic | `Anthropic` | API 调用 | | Ollama | `Ollama` | 本地模型 | | vLLM | `VLLM` | 高性能本地推理 | | SGLang | `SGLang` | 高性能本地推理 | | TGI | `TGI` | Hugging Face 推理端点 | | Llama.cpp | `LlamaCpp` | CPU 高效推理 | | Gemini | `Gemini` | Google AI 模型 | ### 模型初始化示例 ```python from outlines import from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) result = model("Analyze: 'Great product!'", Literal["Positive", "Negative", "Neutral"]) ``` 资料来源：[README.md]() ## LoRA 支持变化 v1.0 版本对 LoRA 加载方式进行了调整： | 版本 | 方式 | 示例 | |------|------|------| | v0 | `model.load_lora(path)` | 直接在模型上调用 | | v1 | 参数传递 | `response = model(..., lora_request=lora_request)` | ```python from outlines import from_vllm from vllm import LLM from vllm.lora.request import LoRARequest model = from_vllm(LLM("microsoft/Phi-3-mini-4k-instruct")) lora_request = LoRARequest("lora_name", 1, "path/to/lora/file") response = model("Write a short story.", lora_request=lora_request) ``` 资料来源：[outlines/release_note.md]() ## 弃用说明 ### v1.0 弃用的功能 | 组件 | 替代方案 | 原因 | |------|----------|------| | `Exllamav2` 模型 | 无替代 | 接口不兼容，维护成本高 | | `Function` 类 | `Application` 类 | 更清晰的职责分离 | | `Generator.load_lora()` | 模型初始化参数或调用参数 | 统一的 LoRA 管理方式 | #### Function 到 Application 的迁移 ```python # v0 from outlines import Function, Template class Character(BaseModel): name: str template = Template.from_string("Create a {{ gender }} character.") fn = Function(template, Character, "hf-internal-testing/tiny-random-GPTJForCausalLM") response = fn(gender="female") # v1 from outlines import Application, Template, from_transformers template = Template.from_string("Create a {{ gender }} character.") app = Application(template, Character) response = app(model, {"gender": "female"}) ``` 资料来源：[outlines/release_note.md]() ## 总结 Outlines 的系统架构通过分层设计实现了灵活且强大的结构化生成能力： 1. **统一 API**：用户通过简单的类型指定即可约束输出 2. **高效编译**：延迟编译和持久缓存优化性能 3. **广泛兼容**：支持多种模型提供商的统一接口 4. **清晰职责**：各层职责分明，便于维护和扩展 --- ## 核心概念 ### 相关页面 相关主题：[系统架构](#page-architecture), [后端系统](#page-backends)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) - [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) - [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py) - [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) - [examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py) - [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py) - [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)
# 核心概念 Outlines 是一个保证 LLM 输出的结构化生成库。其核心理念是：在生成过程中直接约束输出格式，而不是在生成后通过解析、Regex 或脆弱的代码来修复不良输出。 ## 设计理念 ### 问题与解决方案 传统的 LLM 输出处理方式存在以下问题： | 方法 | 问题 | |------|------| | 解析 (Parsing) | 输出可能不遵循预期格式 | | Regex 匹配 | 脆弱且难以维护 | | 后处理代码 | 容易在边界情况下失败 | Outlines 的解决方案是**在生成过程中直接保证结构有效性**，确保输出从一开始就是正确的格式。 ### Outlines 哲学 Outlines 遵循一个简单的模式，模仿 Python 自身的类型系统。只需指定期望的输出类型，Outlines 就会确保数据完全匹配该结构： - 对于是/否响应，使用 `Literal["Yes", "No"]` - 对于数值，使用 `int` 或 `float` - 对于复杂对象，使用 Pydantic 模型定义结构 资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) ## 架构概览 ```mermaid graph TD subgraph "用户层" A[用户代码] --> B[output_type] A --> C[prompt] end subgraph "核心层" B --> D[Generator] C --> D D --> E[Logits 处理器] end subgraph "后端层" E --> F[Transformers] E --> G[VLLM] E --> H[OpenAI] E --> I[Anthropic] E --> J[LlamaCpp] end subgraph "模型层" F --> K[本地模型] G --> L[vLLM Server] H --> M[OpenAI API] I --> N[Anthropic API] J --> O[本地 GGUF] end ``` 资料来源：[outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) ## 输出类型系统 Outlines 支持多种输出类型，用于约束生成内容的结构： ### 基础类型 | 类型 | 说明 | 示例 | |------|------|------| | `int` | 整数 | `model("What's 2+2?", int)` | | `float` | 浮点数 | `model("Temperature?", float)` | | `str` | 字符串 | `model("Name?", str)` | ### Literal 类型 用于有限的选项集合： ```python from typing import Literal result = model("Sentiment?", Literal["Positive", "Negative", "Neutral"]) ``` 资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) ### Pydantic 模型 用于复杂结构化数据： ```python from pydantic import BaseModel class ProductReview(BaseModel): rating: int pros: list[str] cons: list[str] ``` ### Regex 和 DSL ```python from outlines.types import JsonSchema, Regex, integer # 使用 JSON Schema result = model("Answer in JSON", JsonSchema(schema)) # 使用正则表达式 pattern = Regex(r"^[\d]{3}-[\d]{4}$") phone = model("Phone?", pattern) ``` 资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) ## 模型集成 Outlines 支持多种模型后端，提供统一的调用接口： ### 支持的模型类型 | 模型类型 | 说明 | 文档链接 | |----------|------|----------| | `Transformers` | Hugging Face 本地模型 | 资料来源：[examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py) | | `OpenAI` | OpenAI API 模型 | - | | `Anthropic` | Anthropic Claude 模型 | - | | `VLLM` | vLLM 服务端 | - | | `LlamaCpp` | 本地 GGUF 格式模型 | - | | `Gemini` | Google Gemini 模型 | 资料来源：[outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py) | | `SGLang` | SGLang 服务端 | - | ### 异步模型支持 异步模型提供高性能的批量推理能力： ```python from outlines import from_tgi from huggingface_hub import AsyncInferenceClient async_model = outlines.from_tgi( AsyncInferenceClient("http://localhost:11434") ) ``` 资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) ## Generator 类 Generator 是 Outlines v1 的核心组件，用于封装模型和输出类型的组合： ### 特性 - **可重用性**：一次编译，多次生成 - **延迟编译**：输出类型的编译只在第一次生成时进行 - **统一接口**：支持同步和异步调用 ### 使用方式 ```python from outlines import Generator, from_transformers from typing import Literal from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) # 直接调用 result = model("Pizza or burger", Literal["pizza", "burger"]) # 使用 Generator generator = Generator(model, Literal["pizza", "burger"]) result = generator("What's your favorite food?") ``` 资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) ## 模型基类接口 BaseModel 类提供了统一的模型调用接口： ### 核心方法 | 方法 | 说明 | |------|------| | `__call__` | 同步生成单个响应 | | `stream` | 流式生成响应 | | `batch` | 批量生成多个响应 | ### 异步方法 ```python async def stream( self, model_input: Any, output_type: Optional[Any] = None, backend: Optional[str] = None, **inference_kwargs: Any ) -> AsyncIterator[Any] ``` ```python async def batch( self, model_input: List[Any], output_type: Optional[Any] = None, backend: Optional[str] = None, **inference_kwargs: Any ) -> List[Any] ``` 资料来源：[outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) ## 异常处理 Outlines 提供了完整的异常层次结构： ### 异常层次 ``` OutlinesError ├── APIError │ ├── AuthenticationError │ ├── PermissionDeniedError │ ├── NotFoundError │ ├── RateLimitError │ ├── BadRequestError │ ├── ServerError │ ├── APITimeoutError │ ├── APIConnectionError │ └── ProviderResponseError └── GenerationError ``` ### APIError 特性 | 属性 | 类型 | 说明 | |------|------|------| | `provider` | `str \| None` | 提供商名称（如 "openai"） | | `original_exception` | `Exception \| None` | 原始 SDK 异常 | | `status_code` | `int \| None` | HTTP 状态码 | | `request_id` | `str \| None` | 提供商请求 ID | | `retryable` | `bool` | 是否可重试 | | `hint` | `str` | 人类可读的建议 | 资料来源：[outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py) ## 应用场景 ### 函数调用 Outlines 可以将自然语言转换为结构化函数调用： ```python def schedule_meeting( title: str, date: date, duration_minutes: int, attendees: List[str], location: Optional[str] = None ): """安排会议""" return f"会议 '{title}' 已安排" result = model( "I need to set up a meeting tomorrow at 2pm with Alice and Bob", schedule_meeting ) ``` ### 模板系统 使用 Jinja 模板生成动态提示： ```python template = outlines.Template.from_string(""" <|im_start|>user 分析以下 {{ content_type }}的情感： {{ text }} <|im_end|> """) prompt = template(content_type="review", text="Great product!") result = model(prompt, Literal["Positive", "Negative", "Neutral"]) ``` 资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) ### ReAct 模式 实现 ReAct（Reasoning + Acting）模式： ```python def react_generator(prompt, stop=None, max_tokens=128): while True: response = llm(prompt, max_tokens=max_tokens) # 解析 action 和 action_input # 执行 action # 更新 prompt ``` 资料来源：[examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py) ## 快速开始 ### 1. 安装 ```shell pip install outlines ``` ### 2. 连接模型 ```python import outlines from transformers import AutoTokenizer, AutoModelForCausalLM model = outlines.from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) ``` ### 3. 结构化生成 ```python from typing import Literal # 分类 sentiment = model("分析: '这个产品彻底改变了我的生活！'", Literal["Positive", "Negative", "Neutral"]) # 提取数字 temperature = model("水的沸点是多少摄氏度？", int) ``` 资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) ## 版本迁移说明 ### v0 到 v1 的主要变化 | 旧版本 (v0) | 新版本 (v1) | |-------------|--------------| | `Function` 类 | `Application` 类 | | 关键字参数传模板变量 | 字典传模板变量 | | `load_lora()` 方法 | 直接传入 `LoRARequest` | | 模型需先创建生成器 | 模型可直接调用 | ### 废弃的功能 - `Exllamav2` 模型（接口不兼容） - `Function` 类（由 `Application` 替代） - 某些 `load_lora` 方法 资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md) --- ## 输出类型 ### 相关页面 相关主题：[类型系统](#page-type-system), [生成器系统](#page-generator)
相关源码文件 以下源码文件用于生成本页说明： - [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py) - [outlines/types/json_schema_utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/json_schema_utils.py) - [outlines/types/utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/utils.py) - [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py) - [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)
# 输出类型 ## 概述 输出类型（Output Types）是 Outlines 框架的核心概念之一，用于在 LLM 生成过程中约束输出结构，确保模型生成的文本符合预定义的格式规范。Outlines 将用户友好的 Python 类型（如 Pydantic 模型、Literal 类型、内置类型）转换为底层约束机制（正则表达式、FSM），在 token 级别控制生成过程。 输出类型系统的设计遵循"类型驱动 API"原则：用户只需指定期望的输出类型，Outlines 自动处理约束编译和 token 掩码逻辑。 ## 核心类型体系 Outlines 支持多种输出类型，按功能可分为以下几类： ### 内置 Python 类型 | 类型 | 说明 | 示例 | |------|------|------| | `int` | 整数类型 | `model("数字", int)` → `42` | | `float` | 浮点数类型 | `model("温度", float)` → `98.6` | | `str` | 字符串类型 | `model("名称", str)` → `"Alice"` | ### 字面量类型（Literal） 用于生成预定义选项之一： ```python from typing import Literal result = model( "分析情感：'产品很棒！'", Literal["Positive", "Negative", "Neutral"] ) ``` ### Pydantic 模型 复杂结构化输出的首选方式： ```python from pydantic import BaseModel class ProductReview(BaseModel): rating: int pros: list[str] cons: list[str] recommended: bool review = model("分析评论...", ProductReview) ``` ### 正则表达式 DSL 通过 `Regex`、`String`、`integer` 等 Term 类构建正则约束： ```python from outlines.types import Regex, either, at_least # 简单正则 pattern = Regex(r"[A-Z]{2}\d{4}") # 组合正则 complex_pattern = either("yes", "no", "maybe") ``` ## 架构设计 ### 类型转换流程 ```mermaid graph TD A[Python Type] --> B[Term Classes] B --> C[正则表达式] C --> D[FSM 编译] D --> E[Logits Processor] E --> F[Token Masking] F --> G[结构化生成] B --> B1[JsonSchema] B --> B2[CFG] B --> B3[Alternatives] B --> B4[KleeneStar] B --> B5[Literal Term] ``` Outlines 将输出类型处理分为三个逻辑阶段（资料来源：[outlines/types/dsl.py:1-30]()）： 1. **Term 类定义**：包含 JsonSchema、CFG 等独立使用的类型，以及组成正则 DSL 的 Alternatives、KleeneStar 等类 2. **Python 类型到 Term 实例的转换**（`python_types_to_terms` 函数） 3. **Term 实例到正则表达式的转换**（`to_regex` 函数） ### Term 类层次 ``` Term (基类) ├── JsonSchema # JSON Schema 约束 ├── CFG # 上下文无关文法 ├── LiteralTerm # 字面量值 ├── Regex # 正则表达式模式 ├── String # 字符串模式 ├── Integer # 整数模式 ├── Float # 浮点数模式 ├── Alternatives # 或运算 (|) ├── Sequence # 序列连接 ├── KleeneStar # 零或多次 (*) ├── Optional # 可选 (? 隐式) └── Group # 分组 (...) ``` ## JSON Schema 支持 ### JsonSchema 类型 可以直接使用 JSON Schema 字符串作为输出类型（资料来源：[outlines/types/dsl.py:1-30]()）： ```python from outlines.types import JsonSchema json_schema = '{"type": "object", "properties": {"answer": {"type": "number"}}}' result = model("2+2等于几？", JsonSchema(json_schema)) ``` ### Schema 转换工具 `json_schema_utils.py` 提供了 JSON Schema 与 Python 类型之间的双向转换： | 函数 | 功能 | |------|------| | `json_schema_dict_to_pydantic` | JSON Schema → Pydantic 模型 | | `json_schema_dict_to_typeddict` | JSON Schema → TypedDict | | `json_schema_dict_to_dataclass` | JSON Schema → Dataclass | ```python from outlines.types.json_schema_utils import json_schema_dict_to_pydantic schema = { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"} } } PydanticModel = json_schema_dict_to_pydantic(schema) ``` ## 正则表达式 DSL ### Term 函数 Outlines 提供了构建复杂正则模式的组合函数（资料来源：[outlines/types/dsl.py:1-30]()）： | 函数 | 说明 | 示例 | |------|------|------| | `either(*items)` | 或运算 | `either("yes", "no")` | | `optional(term)` | 可选 | `optional("maybe")` | | `at_least(n, term)` | 至少 n 次 | `at_least(3, digit)` | | `integer()` | 整数模式 | 匹配 `-123`, `0`, `456` | | `float_number()` | 浮点数模式 | 匹配 `-1.5`, `3.14` | ### 组合示例 ```python from outlines.types import either, optional, at_least, integer # 复杂模式：电话号码 phone = either("+1", "+86", "") + at_least(10, digit) # 组合多个 Term status = either("pending", "approved", optional("rejected")) ``` ## 类型推断与验证 ### Python 类型检测 `utils.py` 提供了类型检测工具函数（资料来源：[outlines/types/utils.py]()）： | 函数 | 功能 | |------|------| | `is_int(tp)` | 检测是否为整数类型 | | `is_int_instance(val)` | 检测值是否为整数 | | `is_float(tp)` | 检测是否为浮点类型 | | `is_str(tp)` | 检测是否为字符串类型 | | `get_schema_from_signature(fn)` | 从函数签名提取 schema | ### Pydantic 集成 Outlines 利用 Pydantic 的 `GetCoreSchemaHandler` 和 `GetJsonSchemaHandler` 实现类型适配（资料来源：[outlines/types/dsl.py:1-30]()）： ```python class CustomType(BaseModel): value: str @classmethod def __get_pydantic_core_schema__(cls, source, handler): # 自定义 schema 处理逻辑 return handler.generate_schema(cls) ``` ## 与 Generator 的集成 ### Generator 类 Generator 是输出类型的消费者，它接收模型和输出类型，返回可复用的生成器实例（资料来源：[outlines/models/base.py:1-50]()）： ```python from outlines import Generator, from_transformers model = from_transformers(...) generator = Generator(model, MyOutputType) # 复用编译结果 result1 = generator("prompt1") result2 = generator("prompt2") ``` ### Backend 选择 不同输出类型可选择不同的 backend 实现（资料来源：[outlines/backends/__init__.py:1-50]()）： | Backend | 适用类型 | 特点 | |---------|----------|------| | `outlines_core` | Regex, JSON Schema | 通用实现 | | `xgrammar` | JSON Schema | 高性能 | | `llguidance` | Regex | 快速 FSM 编译 | ```python # 指定 backend result = model("prompt", MySchema, backend="xgrammar") ``` ## 工作流程示例 ### 完整生成流程 ```mermaid sequenceDiagram participant User as 用户 participant Model as 模型实例 participant Generator as Generator participant Backend as Backend participant FSM as FSM 编译器 User->>Model: model(prompt, OutputType) Model->>Generator: 创建 Generator(model, OutputType) Generator->>Backend: get_logits_processor(OutputType) Backend->>FSM: 编译约束为 FSM FSM-->>Backend: FSM 状态机 Backend-->>Generator: LogitsProcessor Generator-->>Model: 返回处理后的响应 Model-->>User: 结构化输出结果 ``` ### 实际代码示例 ```python from pydantic import BaseModel from typing import Literal import outlines # 定义输出结构 class AnalysisResult(BaseModel): sentiment: Literal["positive", "negative", "neutral"] confidence: float keywords: list[str] # 使用模型生成 model = outlines.from_transformers(...) result = model("这个产品太棒了！", AnalysisResult) # result 自动类型化为 AnalysisResult 实例 print(result.sentiment) # "positive" ``` ## 最佳实践 ### 1. 优先使用 Pydantic 模型 对于复杂结构，Pydantic 模型比原始 JSON Schema 更易维护： ```python # 推荐 class Response(BaseModel): answer: str confidence: float # 而非 schema = '{"type": "object", "properties": {"answer": {...}}}' ``` ### 2. 善用 Literal 约束 在分类任务中使用 Literal 限制输出范围： ```python result = model(prompt, Literal["A", "B", "C", "D"]) ``` ### 3. 组合使用 DSL 构建特定格式时使用正则 DSL： ```python from outlines.types import Regex, either date_pattern = Regex(r"\d{4}-\d{2}-\d{2}") ``` ## 总结 输出类型系统是 Outlines 实现结构化生成的核心抽象层。它通过将 Python 类型系统与底层 FSM 约束机制解耦，为用户提供了简洁直观的 API。核心设计包括： - **类型驱动**：以 Python 类型作为主要约束规范 - **多层转换**：类型 → Term → 正则 → FSM - **灵活组合**：支持嵌套、组合多种约束类型 - **后端抽象**：允许针对不同场景选择最优实现 开发者只需关注期望的输出结构，Outlines 自动处理底层约束编译和 token 掩码逻辑。 --- ## 类型系统 ### 相关页面 相关主题：[输出类型](#page-output-types), [核心概念](#page-core-concepts)
相关源码文件 以下源码文件用于生成本页说明： - [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py) - [outlines/types/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/__init__.py) - [outlines/grammars/json.lark](https://github.com/dottxt-ai/outlines/blob/main/outlines/grammars/json.lark) - [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py) - [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) - [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)
# 类型系统 ## 概述 Outlines 的类型系统是整个框架的核心基础设施，负责将 Python 类型声明转换为结构化生成的约束条件。该系统采用分层架构设计，从用户友好的 Python 类型逐步编译为底层的有限状态机（FSM），最终在 token 级别控制模型输出的有效性。 类型系统的主要职责包括： - **类型到约束的转换**：将 Pydantic 模型、`Literal` 类型、`int`、`str` 等 Python 类型转换为正则表达式或 FSM - **术语（Term）DSL**：提供 `Regex`、`JsonSchema`、`CFG` 等术语类型，支持复杂输出规范的构建 - **JSON Schema 处理**：支持 JSON Schema 格式的输出规范定义 - **上下文无关文法（CFG）**：支持基于文法的结构化输出约束 资料来源：[outlines/types/dsl.py:1-50]() ## 核心架构 ### 类型系统分层设计 ``` ┌─────────────────────────────────────────────────────────┐ │ 用户层 (User API) │ │ Pydantic BaseModel / Literal / int / JsonSchema / CFG │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 术语层 (Term Layer) │ │ Term 类: JsonSchema, CFG, Regex, String, ... │ │ 组合函数: either, optional, at_least, ... │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 正则表达式层 (Regex Layer) │ │ to_regex() → Python re.Pattern 对象 │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ FSM 编译层 (outlines-core) │ │ build_regex_from_schema() → FSM │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Logits 处理层 │ │ 处理器/guide.py: FSM 状态管理与 token 掩码 │ └─────────────────────────────────────────────────────────┘ ``` ### 类型转换流程 ```mermaid graph LR A[Python 类型] --> B[Term 实例
python_types_to_terms] B --> C[正则表达式
to_regex] C --> D[FSM 有限状态机
outlines-core] D --> E[Token 掩码
Logits Processor] E --> F[结构化输出] A1[Pydantic Model] --> A A2[Literal Type] --> A A3[int / float] --> A A4[JsonSchema] --> B A5[CFG 文法] --> B ``` ## 核心组件详解 ### 术语类（Term Classes） 类型系统中的所有术语类都继承自统一接口，支持转换为正则表达式。核心术语类包括： | 术语类 | 用途 | 源码位置 | |--------|------|----------| | `JsonSchema` | 基于 JSON Schema 的输出约束 | [dsl.py:50-80]() | | `CFG` | 上下文无关文法约束 | [dsl.py:80-110]() | | `Regex` | 直接使用正则表达式模式 | [dsl.py:110-140]() | | `String` | 字符串字面量约束 | [dsl.py:140-170]() | | `Alternatives` | 多选一约束（对应正则 `\|`） | [dsl.py:170-200]() | | `KleeneStar` | 零次或多次重复（对应 `*`） | [dsl.py:200-230]() | | `Optional` | 可选约束（对应 `?`） | [dsl.py:230-260]() | ### DSL 组合函数 类型系统提供了丰富的组合函数，用于构建复杂的输出规范： ```python from outlines.types import either, optional, at_least, integer # either: 匹配多个选项之一 choice = either("option_a", "option_b", "option_c") # optional: 可选的元素 element = optional("prefix:") # at_least: 至少重复次数 repeated = at_least(integer(), min_times=1) # integer: 整数类型 num = integer() ``` 资料来源：[outlines/types/dsl.py:200-280]() ### Python 类型到 Term 的转换 `python_types_to_terms()` 函数负责将标准 Python 类型转换为 Term 实例： | Python 类型 | 转换目标 | 示例 | |-------------|----------|------| | `int` | `integer()` | `int` → 整数约束 | | `float` | `float_()` | `float` → 浮点数约束 | | `str` | `string()` | `str` → 字符串约束 | | `bool` | `literal(True/False)` | `bool` → 布尔约束 | | `Literal["A", "B"]` | `alternatives(...)` | 枚举值约束 | | `Enum` | `alternatives(...)` | 枚举类约束 | | `List[T]` | `array(term_from(T))` | 列表约束 | | `Dict[K, V]` | `object(...)` | 字典约束 | ```python def python_types_to_terms(py_type: Any) -> Term: """将 Python 类型递归转换为 Term 实例""" # 处理 Literal 类型 if is_literal(py_type): return alternatives(*get_args(py_type)) # 处理枚举类型 if is_enum(py_type): return alternatives(*[e.value for e in py_type]) # 处理列表类型 if is_list(py_type): element_type = get_args(py_type)[0] return array(python_types_to_terms(element_type)) # ... 更多类型处理 ``` 资料来源：[outlines/types/dsl.py:300-400]() ## 输出类型（Output Types） ### 内置输出类型 Outlines 支持多种输出类型，可直接作为模型调用的第二个参数： ```python from typing import Literal from pydantic import BaseModel # 简单类型 result = model("What's 2+2?", int) # 输出整数 # 字面量类型 sentiment = model("Great product!", Literal["positive", "negative", "neutral"]) # Pydantic 模型 class User(BaseModel): name: str age: int email: str user = model("Extract user info", User) ``` ### JsonSchema 类型 `JsonSchema` 术语允许直接使用 JSON Schema 字符串定义输出结构： ```python from outlines.types import JsonSchema json_schema = ''' { "type": "object", "properties": { "answer": {"type": "number"} } } ''' result = model("What's 2+2?", JsonSchema(json_schema)) ``` 资料来源：[outlines/release_note.md:80-100]() ### CFG（上下文无关文法） CFG 允许使用 Lark 语法定义自定义文法： ```python from outlines.types import CFG grammar = """ start: expression expression: term ((ADD | SUB) term)* term: factor ((MUL | DIV) factor)* factor: NUMBER | "(" expression ")" ADD: "+" SUB: "-" MUL: "*" DIV: "/" NUMBER: /[0-9]+/ """ result = model("Calculate 2+3*4", CFG(grammar)) ``` 资料来源：[outlines/grammars/json.lark]() 及 [outlines/types/dsl.py]() ## JSON Schema 与 Pydantic 互转 类型系统提供了 JSON Schema 与其他格式的双向转换能力： ### JSON Schema 转 Pydantic ```python from outlines.types.json_schema_utils import json_schema_dict_to_pydantic schema = { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"} } } PydanticModel = json_schema_dict_to_pydantic(schema) ``` ### JSON Schema 转 TypedDict ```python from outlines.types.json_schema_utils import json_schema_dict_to_typeddict TypedDictModel = json_schema_dict_to_typeddict(schema) ``` ### JSON Schema 转 Dataclass ```python from outlines.types.json_schema_utils import json_schema_dict_to_dataclass DataClassModel = json_schema_dict_to_dataclass(schema) ``` 资料来源：[outlines/types/dsl.py:60-90]() ## 与生成器的集成 ### Generator 类 `Generator` 类封装了模型和输出类型，提供了可复用的生成接口： ```python from outlines import Generator, from_transformers model = from_transformers(...) # 创建生成器，输出类型编译一次 generator = Generator(model, MyOutputType) # 多次复用同一生成器 result1 = generator("prompt1") result2 = generator("prompt2") ``` ### 模型直接调用 模型也可以直接调用，类型系统在每次调用时编译： ```python # 直接调用方式 result = model("prompt", MyOutputType) # 等价于使用 Generator generator = Generator(model, MyOutputType) result = generator("prompt") ``` 资料来源：[outlines/models/base.py:100-150]() ## 异常处理 类型系统在遇到无效类型或转换错误时，会抛出标准化的异常： | 异常类 | 描述 | 源码位置 | |--------|------|----------| | `OutlinesError` | 基础异常类 | [exceptions.py:30]() | | `APIError` | API 相关错误基类 | [exceptions.py:35]() | | `ProviderResponseError` | 提供商响应错误 | [exceptions.py:55]() | | `GenerationError` | 生成过程中的错误 | [exceptions.py:60]() | ```python try: result = model("prompt", InvalidType) except OutlinesError as e: print(f"类型系统错误: {e}") ``` 资料来源：[outlines/exceptions.py:20-70]() ## 完整使用示例 ```python import outlines from typing import Literal, List from pydantic import BaseModel from enum import Enum # 定义枚举类型 class Category(str, Enum): TECH = "technology" FOOD = "food" TRAVEL = "travel" # 定义 Pydantic 模型 class Article(BaseModel): title: str summary: str category: Category tags: List[str] published: bool # 初始化模型 model = outlines.from_transformers(...) # 提取结构化信息 article = model( "Write about AI advancements in healthcare", Article ) # 使用字面量类型快速分类 sentiment = model( "The new iPhone is amazing!", Literal["positive", "negative", "neutral"] ) ``` ## 模块导出 `outlines.types` 模块的公共 API： ```python # outlines/types/__init__.py 导出 __all__ = [ "Term", # 基础术语类 "JsonSchema", # JSON Schema 术语 "CFG", # 上下文无关文法 "Regex", # 正则表达式术语 "String", # 字符串术语 "integer", # 整数术语工厂函数 "float_", # 浮点数术语工厂函数 "string", # 字符串术语工厂函数 "either", # 组合函数：或 "optional", # 组合函数：可选 "at_least", # 组合函数：至少 "alternatives", # 组合函数：多选一 "array", # 组合函数：数组 "object", # 组合函数：对象 ] ``` 资料来源：[outlines/types/__init__.py]() --- ## 模型提供者 ### 相关页面 相关主题：[生成器系统](#page-generator)
相关源码文件 以下源码文件用于生成本页说明： - [outlines/models/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/__init__.py) - [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) - [outlines/models/transformers.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/transformers.py) - [outlines/models/openai.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/openai.py) - [outlines/models/vllm.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/vllm.py) - [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py) - [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md) - [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)
# 模型提供者 ## 概述 模型提供者（Model Providers）是 Outlines 框架中负责与不同大语言模型后端进行交互的核心抽象层。Outlines 实现了统一的接口，使得用户可以使用相同的代码调用方式访问来自不同提供商的模型，包括本地 transformers 模型、OpenAI、Anthropic、vLLM 等。 Outlines 的核心设计理念是"**任何模型都适用**"——相同的代码可以在不同的模型提供商之间切换而无需修改业务逻辑。这种设计通过模型提供者架构实现，将模型交互的细节封装在统一的接口之后。资料来源：[README.md:1-10]() ## 架构设计 ### 分层架构 ``` 用户 API (outlines.models) ↓ 生成器类 (SteerableGenerator, BlackBoxGenerator) ↓ 类型系统 (types/dsl.py: Pydantic → JsonSchema → Regex) ↓ FSM 编译 (outlines-core: regex → FSM via interegular) ↓ Guide 系统 (processors/guide.py: FSM 状态管理) ↓ Logits 处理 (processors/structured.py: token 掩码) ↓ 模型提供者 (transformers, OpenAI, 等) ``` ### 模型类层次结构 Outlines 中的模型类分为两大类别： | 类别 | 描述 | 控制层级 | 支持的提供者 | |------|------|----------|--------------| | **SteerableModel** | 可操纵模型 | 完全控制 logits | transformers, llama.cpp, vLLM | | **BlackBoxModel** | 黑盒模型 | 通过 API 调用 | OpenAI, Anthropic, Google Gemini | 资料来源：[llm.txt:1-25]() ### 基类设计 所有模型提供者都继承自 `BaseModel` 类，该类定义了共享的 `__call__`、`batch` 和 `stream` 方法。模型类必须定义 `type_adapter` 属性（类型为 `ModelTypeAdapter`），用于格式化输入和输出类型。 ```python # outlines/models/base.py class BaseModel(ABC): """所有异步模型的基类""" type_adapter: ModelTypeAdapter tensor_library_name: str async def __call__( self, model_input: Any, output_type: Optional[Any] = None, backend: Optional[str] = None, **inference_kwargs: Any ) -> Any: """直接调用模型""" ``` 资料来源：[outlines/models/base.py:1-50]() ## 支持的模型提供者 ### 本地模型提供者 #### Transformers `Transformers` 提供者允许使用 Hugging Face Transformers 库加载的本地模型。这是 Outlines 最基础的提供者，通过完全控制 logits 实现结构化生成。 ```python import outlines from transformers import AutoModelForCausalLM, AutoTokenizer model = outlines.from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) result = model("What's 2 + 2?", int) ``` 资料来源：[README.md:40-55]() #### vLLM `vLLM` 提供者支持通过 vLLM 推理引擎运行模型，提供高效的批量推理能力。 ```python from outlines import from_vllm model = from_vllm( "microsoft/Phi-3-mini-4k-instruct" ) result = model("Pizza or burger", Literal["pizza", "burger"]) ``` 资料来源：[outlines/release_note.md:80-90]() #### Llama.cpp 支持通过 llama.cpp 进行 CPU 或 GPU 推理的模型。 ### API 模型提供者 #### OpenAI `OpenAI` 提供者封装了 OpenAI API，支持 GPT-4、GPT-3.5-Turbo 等模型。 #### Anthropic 支持 Claude 系列模型的调用。 #### Google Gemini `Gemini` 提供者封装了 Google AI 的 Gemini 模型： ```python from outlines import from_gemini from google.genai import Client model = from_gemini(Client(api_key="your-api-key")) ``` 资料来源：[outlines/models/gemini.py:1-30]() ### 异步推理端点 Outlines 还支持异步推理端点，特别适用于生产环境： | 提供者 | 类名 | 描述 | |--------|------|------| | SGLang | `AsyncSGLang` | 异步 SGLang 推理服务器 | | TGI | `AsyncTGI` | 异步 Text Generation Inference 服务器 | | vLLM | `AsyncVLLM` | 异步 vLLM 推理服务器 | ```python from outlines import from_tgi from huggingface_hub import AsyncInferenceClient async_model = outlines.from_tgi(AsyncInferenceClient("http://localhost:11434")) ``` 资料来源：[outlines/release_note.md:60-70]() ## 核心接口 ### 模型调用方法 所有模型提供者都实现了以下核心方法： #### `__call__` - 单次生成 ```python result = model("Your prompt here", output_type) ``` #### `stream` - 流式生成 ```python for chunk in model.stream("Your prompt here", output_type): print(chunk) ``` #### `batch` - 批量生成 ```python results = model.batch( ["prompt1", "prompt2", "prompt3"], output_type ) ``` 资料来源：[outlines/models/base.py:50-120]() ### 推理参数 | 参数 | 类型 | 描述 | |------|------|------| | `model_input` | Any | 输入提示或提示列表 | | `output_type` | Optional[Any] | 输出类型约束 | | `backend` | Optional[str] | 后端名称（用于可操纵模型） | | `**inference_kwargs` | Any | 额外推理参数（如 max_tokens, temperature） | ## 使用模式 ### 模式一：直接模型调用 ```python from typing import Literal from outlines import from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) # 直接调用 result = model("What's 2 + 2?", int) # 返回 4 ``` ### 模式二：使用生成器 生成器模式允许重用编译后的输出类型，提高批量调用效率： ```python from outlines import Generator, from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) # 创建生成器，输出类型只编译一次 generator = Generator(model, int) # 多次使用同一生成器 result1 = generator("What's 2 + 2?") result2 = generator("What's 5 + 3?") ``` 资料来源：[outlines/release_note.md:90-105]() ### 模式三：Pydantic 模型输出 ```python from pydantic import BaseModel from enum import Enum class Rating(Enum): poor = 1 fair = 2 good = 3 excellent = 4 class ProductReview(BaseModel): rating: Rating pros: list[str] cons: list[str] summary: str review = model("生成一个产品评价", ProductReview) ``` ## LoRA 支持 ### vLLM LoRA 加载 vLLM 模型支持通过 `lora_request` 参数加载 LoRA 适配器： ```python from outlines import from_vllm from vllm import LLM from vllm.lora.request import LoRARequest model = from_vllm(LLM("microsoft/Phi-3-mini-4k-instruct")) lora_request = LoRARequest("my_lora", 1, "path/to/lora/file") result = model("Write a short story", str, lora_request=lora_request) ``` 资料来源：[outlines/release_note.md:110-125]() ## 版本变更说明 ### v1.0 主要变更 在 Outlines v1.0 中，模型接口经历了重大修改： | 变更项 | 旧版本 | 新版本 | |--------|--------|--------| | 调用方式 | 先创建生成器再调用 | 直接 `model(prompt, output_type)` | | 流式接口 | 需创建特定生成器 | 所有模型都有 `stream` 方法 | | LoRA 加载 | `model.load_lora()` | 通过参数传递 `lora_request` | ### 已弃用的提供者 - **Exllamav2**: 由于接口不完全兼容，已从 Outlines 中移除 资料来源：[outlines/release_note.md:30-50]() ## 最佳实践 ### 1. 选择合适的提供者 ```mermaid graph TD A[开始] --> B{需求场景} B -->|需要完全控制| C[SteerableModel] B -->|使用云端API| D[BlackBoxModel] C -->|HuggingFace模型| E[Transformers] C -->|高吞吐需求| F[vLLM] D -->|OpenAI生态| G[OpenAI] D -->|Anthropic生态| H[Anthropic] ``` ### 2. 性能优化建议 - **批量处理**：使用 `batch` 方法进行批量推理，减少 API 调用开销 - **生成器复用**：频繁调用同一输出类型时使用 `Generator` 避免重复编译 - **本地缓存**：transformers 模型首次加载后会被缓存 ### 3. 生产环境部署 对于生产环境，推荐使用异步推理端点： ```python # 推荐的生产配置 async_model = outlines.from_vllm( AsyncInferenceClient("http://your-vllm-server:8000") ) ``` ## 相关模块 - [Generator](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py) - 生成器核心类 - [Type System](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py) - 类型系统与约束编译 - [FSM Compilation](https://github.com/dottxt-ai/outlines/blob/main/outlines_core) - 有限状态机编译 --- ## 生成器系统 ### 相关页面 相关主题：[系统架构](#page-architecture), [模型提供者](#page-model-providers)
相关源码文件 以下源码文件用于生成本页说明： - [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py) - [outlines/inputs.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/inputs.py) - [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py) - [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py) - [outlines/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/__init__.py)
# 生成器系统 ## 概述 生成器系统（Generator System）是 Outlines 框架的核心抽象层，负责将结构化输出类型与语言模型解耦，实现可复用、可组合的生成管线。生成器接收模型实例和输出类型作为构造参数，返回一个可迭代的生成器对象，用户可反复使用该对象进行结构化文本生成而无需每次重新指定输出类型。 生成器系统的核心价值在于**延迟编译和复用机制**：输出类型的有限状态机（FSM）仅在首次使用时编译一次，后续调用直接复用已编译的状态机，显著提升高频调用场景的性能。资料来源：[release_note.md]() ## 架构设计 ### 层级结构 ``` 用户代码 (User Code) ↓ ┌─────────────────────────────────────┐ │ Generator (生成器) │ │ - 持有模型引用与输出类型 │ │ - 管理 FSM 编译与缓存 │ │ - 提供同步/异步生成接口 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Model (模型适配器) │ │ - SteerableModel / BlackBoxModel │ │ - logits 处理 / API 调用封装 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 输出类型系统 (Output Types) │ │ - Pydantic → JsonSchema → Regex │ │ - FSM 编译 (outlines-core) │ └─────────────────────────────────────┘ ``` ### 关键设计决策 | 决策 | 说明 | |------|------| | **惰性编译** | FSM 在首次调用时编译并持久化缓存 | | **统一接口** | 同步/异步、流式/批量使用相同 API | | **模型无关** | 支持本地模型(transformers)和 API 模型(OpenAI) | | **类型驱动** | Python 类型注解是主要的约束声明方式 | 资料来源：[llm.txt]() ## 核心组件 ### Generator 类 `Generator` 是生成器系统的核心类，封装了模型实例、输出类型和编译后的 FSM。 **构造函数签名：** ```python Generator(model, output_type, backend=None) ``` | 参数 | 类型 | 说明 | |------|------|------| | `model` | `Model` | 已初始化的 Outlines 模型实例 | | `output_type` | `type` | Python 类型或类型别名（int, Literal, BaseModel 等） | | `backend` | `str \| None` | 后端名称，仅用于可转向模型(steerable models) | 资料来源：[outlines/generator.py]() ### 同步生成方法 ```python # 单次生成 result = generator("prompt", **inference_kwargs) # 批量生成 results = generator.batch(["prompt1", "prompt2"], **inference_kwargs) ``` | 方法 | 参数 | 返回值 | |------|------|--------| | `__call__` | `prompt`, `**inference_kwargs` | `Any`（单条生成结果） | | `batch` | `List[prompt]`, `**inference_kwargs` | `List[Any]`（批量结果列表） | 资料来源：[outlines/models/base.py:1-100]() ### 异步生成方法 ```python # 异步单次生成 result = await generator("prompt", **inference_kwargs) # 异步批量生成 results = await generator.batch(["prompt1", "prompt2"], **inference_kwargs) # 流式生成 async for chunk in generator.stream("prompt", **inference_kwargs): print(chunk) ``` | 方法 | 参数 | 返回值 | |------|------|--------| | `__call__` (async) | `prompt`, `**inference_kwargs` | `Coroutine[Any]` | | `batch` (async) | `List[prompt]`, `**inference_kwargs` | `Coroutine[List[Any]]` | | `stream` (async) | `prompt`, `**inference_kwargs` | `AsyncIterator[Any]` | 资料来源：[outlines/models/base.py:100-200]() ## 输入处理系统 `outlines/inputs.py` 负责处理各种格式的模型输入，将其标准化为统一的内部表示。 ### 输入类型支持 | 输入类型 | 说明 | 示例 | |----------|------|------| | 字符串 | 纯文本 prompt | `"今天天气如何？"` | | 消息列表 | 对话格式 | `[{"role": "user", "content": "..."}]` | | 模板对象 | Jinja 模板渲染后的字符串 | `template(content="...")` | 资料来源：[outlines/inputs.py]() ## 异常处理体系 Outlines 定义了完整的异常层次结构，所有公共异常继承自 `OutlinesError` → `APIError` → `Exception`。 ### 异常类层次 ``` OutlinesError └── APIError (provider: str, status_code: int, request_id: str) ├── AuthenticationError (401) ├── PermissionDeniedError (403) ├── NotFoundError (404) ├── BadRequestError (400) ├── RateLimitError (429) ├── ServerError (5xx) ├── APITimeoutError └── APIConnectionError └── ProviderResponseError └── GenerationError ``` ### 异常属性 | 属性 | 类型 | 说明 | |------|------|------| | `provider` | `str \| None` | 提供商名称（如 `"openai"`） | | `status_code` | `int \| None` | HTTP 状态码 | | `request_id` | `str \| None` | 请求追踪 ID | | `retryable` | `bool` | 是否可重试 | | `hint` | `str` | 用户友好的建议信息 | 资料来源：[outlines/exceptions.py]() ## 使用模式 ### 模式一：直接模型调用 vs 生成器调用 **直接调用模式（v1 新增）：** ```python from typing import Literal from outlines import from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) result = model("Pizza or burger", Literal["pizza", "burger"]) ``` **生成器模式（可复用）：** ```python from pydantic import BaseModel from outlines import Generator, from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer class Character(BaseModel): name: str model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) generator = Generator(model, Character) # 多次调用无需重新指定输出类型 response1 = generator("Create a male character.") response2 = generator("Create a female character.") ``` 资料来源：[release_note.md]() ### 模式二：流式生成 ```python from outlines import Generator, from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) generator = Generator(model, str) # 同步流式（需调用 stream 方法） for chunk in generator.stream("Write a story about a cat"): print(chunk, end="", flush=True) ``` ### 模式三：异步批量处理 ```python import asyncio from outlines import Generator, from_transformers from transformers import AutoModelForCausalLM, AutoTokenizer async def main(): model = from_transformers( AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"), AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct") ) generator = Generator(model, str) prompts = [f"Analyze sentiment: {text}" for text in texts] results = await generator.batch(prompts) return results asyncio.run(main()) ``` ## API 模型生成器 对于 API 类模型（如 OpenAI、Anthropic），生成器通过 `BlackBoxModel` 封装，利用提供商的结构化输出支持。 ### OpenAI 示例 ```python from openai import OpenAI from pydantic import BaseModel from outlines import Generator, from_openai class Character(BaseModel): name: str age: int client = OpenAI() model = from_openai(client) generator = Generator(model, Character) result = generator("Create a character named Alice, age 25") ``` 资料来源：[release_note.md]() ## 工作流程图 ```mermaid graph TD A[创建 Generator] --> B{输出类型已编译?} B -->|否| C[调用 FSM 编译] C --> D[缓存 FSM] B -->|是| E[复用缓存 FSM] E --> F[准备 Prompt] D --> F F --> G{模型类型} G -->|Steerable| H[应用 Logits Processor] G -->|BlackBox| I[调用 API 结构化输出] H --> J[采样下一个 Token] I --> K[解析结构化响应] J --> L{是否结束?} L -->|否| J L -->|是| M[返回结果] K --> M ``` ## 版本迁移指南 ### v0 到 v1 的变化 | v0 方式 | v1 方式 | |---------|---------| | `generate.json(model, Character)` | `Generator(model, Character)` | | `models.openai("gpt-4o")` | `from_openai(OpenAI())` | | `generator(prompt)` | `generator(prompt)` | | `model.load_lora(...)` | `lora_request=LoRARequest(...)` | 资料来源：[release_note.md]() ## 最佳实践 1. **重复使用生成器**：创建生成器后应复用，避免重复编译 FSM 2. **选择合适的输出类型**：简单类型用 `Literal`，复杂结构用 Pydantic 3. **处理异常**：使用 `try/except OutlinesError` 捕获结构化错误 4. **流式输出**：长文本生成使用流式接口改善用户体验 5. **批量处理**：多 prompt 场景使用 `batch` 方法提高吞吐量 ## 相关模块 | 模块 | 路径 | 职责 | |------|------|------| | 生成器核心 | `outlines/generator.py` | Generator 类实现 | | 输入处理 | `outlines/inputs.py` | Prompt 标准化 | | 异常定义 | `outlines/exceptions.py` | 错误类型定义 | | 模型基类 | `outlines/models/base.py` | 模型抽象接口 | | 模型实现 | `outlines/models/*.py` | 各提供商适配器 | --- ## 后端系统 ### 相关页面 相关主题：[系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py) - [outlines/backends/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/base.py) - [outlines/backends/outlines_core.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/outlines_core.py) - [outlines/backends/xgrammar.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/xgrammar.py) - [outlines/backends/llguidance.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/llguidance.py)
# 后端系统 ## 概述 Outlines 的后端系统是负责将结构化输出约束（如正则表达式、JSON Schema、Pydantic 模型等）转换为模型推理过程中可执行的日志处理器（Logits Processor）的核心模块。该系统通过抽象化的后端接口，支持多种底层约束编译引擎，使用户能够在不同的生成场景中灵活选择最合适的约束实现方式。 后端系统在整个 Outlines 架构中扮演着关键角色，它位于类型系统（Type System）与模型推理层之间，负责将高级约束描述编译为低级的有限状态机（FSM）或指导序列（Guide），并生成对应的日志处理器来控制 token 的生成过程。 资料来源：[llm.txt]() ## 架构设计 ### 层级架构 ``` 用户 API (outlines.models) ↓ 生成器类 (SteerableGenerator, BlackBoxGenerator) ↓ 类型系统 (types/dsl.py: Pydantic → JsonSchema → Regex) ↓ FSM 编译层 (outlines-core: regex → FSM via interegular) ↓ 后端系统 (backends/: 抽象接口与多种实现) ↓ 日志处理 (processors/structured.py: token masking) ↓ 模型提供者 (transformers, OpenAI, etc.) ``` ### 后端抽象设计 Outlines 采用后端抽象模式，为不同的约束编译引擎提供统一的接口。所有的后端实现都继承自基类 `Backend`，该基类定义了后端必须实现的核心方法，包括约束编译、状态管理和日志处理等。 ```mermaid graph TD A[用户调用 Generator] --> B[Backend 抽象层] B --> C[OutlinesCore 后端] B --> D[XGrammar 后端] B --> E[LLGuidance 后端] C --> F[interegular 编译 FSM] D --> G[XGrammar 库] E --> H[llguidance 库] ``` 资料来源：[outlines/backends/base.py]() ## 核心组件 ### 后端基类 (Backend) 所有具体后端实现都需要继承 `Backend` 基类，该类定义了统一的后端接口： | 方法名 | 功能描述 | 返回类型 | |--------|----------|----------| | `__init__` | 初始化后端实例 | None | | `name` | 返回后端标识名称 | str | | `__call__` | 执行约束编译 | Any | | `fsm_graph` | 获取 FSM 图结构 | FSMGraph | | `get一方文和_状态` | 获取当前 FSM 状态 | int | | `reset` | 重置 FSM 状态 | None | 资料来源：[outlines/backends/base.py]() ### OutlinesCore 后端 `OutlinesCore` 是 Outlines 的默认后端实现，基于 `interegular` 库将正则表达式转换为有限状态机。该后端利用 `outlines-core` 包的底层能力，实现高效的 FSM 编译和状态管理。 **核心特性：** - 使用 `interegular` 库进行正则表达式解析和 FSM 转换 - 支持缓存已编译的 FSM 以提高性能 - 兼容所有基于 FSM 的约束类型 **工作流程：** ```mermaid graph LR A[正则表达式/约束] --> B[interegular 解析] B --> C[FSM 构建] C --> D[状态缓存] D --> E[Logits Processor] ``` 资料来源：[outlines/backends/outlines_core.py]() ### XGrammar 后端 `XGrammar` 后端是由 MLC-LLM 社区开发的高性能约束编译引擎，专为结构化生成设计。该后端提供了比默认实现更快的约束匹配速度，特别适合对延迟敏感的应用场景。 **主要优势：** - 高度优化的状态转移算法 - 支持字节级（byte-level）约束 - 更低的内存占用 资料来源：[outlines/backends/xgrammar.py]() ### LLGuidance 后端 `LLGuidance` 后端提供了另一种结构化生成的实现方式，支持更复杂的约束语法和模式匹配能力。该后端适合需要高级约束特性的高级用户。 **支持的功能：** - 复杂的正则表达式模式 - 自定义终止条件 - 多模态约束支持 资料来源：[outlines/backends/llguidance.py]() ## 后端注册与选择机制 ### 后端初始化 Outlines 通过后端注册机制管理可用的后端实现。用户可以在创建生成器时指定使用哪个后端： ```python from outlines import Generator, from_transformers model = from_transformers("microsoft/Phi-3-mini-4k-instruct") # 使用默认后端 generator = Generator(model, MySchema) # 指定特定后端 generator = Generator(model, MySchema, backend="xgrammar") ``` 资料来源：[outlines/backends/__init__.py]() ### 后端自动选择 当用户未指定后端时，Outlines 会根据以下优先级自动选择可用的后端： 1. **OutlinesCore**（默认）- 最广泛的兼容性 2. **XGrammar** - 高性能场景 3. **LLGuidance** - 高级约束需求 ## FSM 状态管理 ### 状态转换机制 FSM（有限状态机）是约束编译的核心数据结构。每个 FSM 由多个状态节点和状态转移边组成，模型在生成每个 token 时都会根据当前状态确定合法的下一个 token 集合。 ```mermaid graph TD S0[状态 0: 初始状态] -->|token A| S1[状态 1] S0 -->|token B| S2[状态 2] S1 -->|token C| S1 S1 -->|token D| S3[状态 3: 终止] S2 -->|token E| S3 S3 -->|"[END]"| S4[完成] ``` ### 状态缓存 Outlines 支持 FSM 缓存机制，避免对相同约束重复编译。缓存键由约束的哈希值和版本号组成，确保缓存的一致性和有效性。 资料来源：[outlines/backends/outlines_core.py]() ## 与生成器系统的集成 ### SteerableGenerator `SteerableGenerator` 是用于可控模型（如 Transformers、llama.cpp）的生成器类。它直接调用后端系统来创建日志处理器，在推理过程中实时过滤不合法的 token。 ```python generator = Generator(model, output_type, backend) result = generator("提示词") ``` ### BlackBoxGenerator `BlackBoxGenerator` 用于黑盒 API 模型（如 OpenAI、Anthropic）。这类模型不支持直接的日志处理，因此后端系统会生成符合模型原生结构化输出格式的提示。 资料来源：[outlines/models/base.py]() ## 配置选项 ### 后端级配置 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `backend` | str | "outlines_core" | 指定使用的后端引擎 | | `cache_dir` | Path | None | FSM 缓存目录 | | `enable_cache` | bool | True | 是否启用 FSM 缓存 | | `fsm_options` | dict | {} | 后端特定配置项 | ### 运行时配置 在调用生成器时可以传递推理参数，这些参数会与后端的约束处理机制协同工作： ```python result = model( "提示词", temperature=0.7, max_tokens=100, num_beams=2 ) ``` ## 扩展后端 ### 自定义后端接口 要实现自定义后端，需要继承 `Backend` 基类并实现以下方法： 1. `__init__(self, ...)`: 初始化后端 2. `name(self) -> str`: 返回后端名称 3. `__call__(self, ...) -> LogitsProcessor`: 创建日志处理器 4. `fsm_graph(self) -> FSMGraph`: 返回 FSM 图结构 ### 注册自定义后端 自定义后端可以通过修改 `backends/__init__.py` 来注册到 Outlines 系统中。 资料来源：[outlines/backends/__init__.py]() ## 性能考量 ### 后端性能对比 | 后端 | 编译速度 | 推理速度 | 内存占用 | 兼容性 | |------|----------|----------|----------|--------| | OutlinesCore | 中等 | 中等 | 中等 | 高 | | XGrammar | 快 | 快 | 低 | 中 | | LLGuidance | 慢 | 快 | 高 | 中 | ### 优化建议 - **重复约束**：启用 FSM 缓存以避免重复编译 - **高频调用**：考虑使用 XGrammar 后端以获得更低的延迟 - **复杂约束**：使用 LLGuidance 后端的扩展语法支持 ## 错误处理 ### 后端相关异常 后端系统可能抛出的异常类型包括： | 异常类型 | 触发场景 | 处理建议 | |----------|----------|----------| | `BackendNotAvailableError` | 请求的后端不可用 | 检查后端安装或使用备选后端 | | `CompilationError` | 约束编译失败 | 检查约束语法是否正确 | | `FSMCacheError` | 缓存读写失败 | 检查缓存目录权限 | 资料来源：[outlines/exceptions.py]() ## 相关文档 - [核心特性文档](https://dottxt-ai.github.io/outlines/latest/features/core/generator) - [模型集成指南](https://dottxt-ai.github.io/outlines/latest/features/models) - [输出类型参考](https://dottxt-ai.github.io/outlines/latest/features/core/ouput_types) --- --- ## Doramagic 踩坑日志 项目：dottxt-ai/outlines 摘要：发现 29 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] Streaming structured generation with partial validation。 ## 1. 安装坑 · 来源证据：[Feature] Streaming structured generation with partial validation - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 配置坑 · 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 维护坑 · 来源证据：Add more custom types - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 安全/权限坑 · 来源证据：Add function calling and MCP support - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 安全/权限坑 · 来源证据：[Feature Request] Add streaming support for structured generation - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 6. 安装坑 · 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes - 对用户的影响：Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Incompatibility with vllm==0.19 because of some api changes. Context: Observed when using python, cuda - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_9f23e49bc91e3f8af003ddcdedec3e72 | https://github.com/dottxt-ai/outlines/issues/1854 | Incompatibility with vllm==0.19 because of some api changes ## 7. 安装坑 · 失败模式：installation: Outlines v1.2.6 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.6 - 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.6 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup. - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6 ## 8. 安装坑 · 失败模式：installation: Outlines v1.2.8 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.8 - 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.8 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8 ## 9. 安装坑 · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。 ## 10. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass. ## 11. 维护坑 · 失败模式：migration: Outlines v1.2.10 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this migration risk before relying on the project: Outlines v1.2.10 - 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.10 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10 ## 12. 维护坑 · 失败模式：migration: Outlines v1.3.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this migration risk before relying on the project: Outlines v1.3.0 - 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.3.0 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration. - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0 ## 13. 维护坑 · 来源证据：Complex structure makes output empty - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 14. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing ## 15. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作: 下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium ## 16. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium ## 17. 安全/权限坑 · 来源证据：Incompatibility with vllm==0.19 because of some api changes - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Incompatibility with vllm==0.19 because of some api changes - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_45101a3eaffb4eda98b4d597dd5aca64 | https://github.com/dottxt-ai/outlines/issues/1854 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 18. 安全/权限坑 · 来源证据：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_85cb7bc56eb64613b9ec65e51dea90e9 | https://github.com/dottxt-ai/outlines/issues/1847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 19. 能力坑 · 失败模式：capability: Add function calling and MCP support - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Add function calling and MCP support - 对用户的影响：Developers may hit a documented source-backed failure mode: Add function calling and MCP support - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add function calling and MCP support. Context: Observed when using python - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_dfb58c522eebbd15e72f7bfbfc936335 | https://github.com/dottxt-ai/outlines/issues/1626 | Add function calling and MCP support ## 20. 能力坑 · 失败模式：capability: Add more custom types - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Add more custom types - 对用户的影响：Developers may hit a documented source-backed failure mode: Add more custom types - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add more custom types. Context: Source discussion did not expose a precise runtime context. - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_8ba5f20b34d61b76171e5fdc02fffff8 | https://github.com/dottxt-ai/outlines/issues/1303 | Add more custom types ## 21. 能力坑 · 失败模式：capability: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set - 对用户的影响：Developers may hit a documented source-backed failure mode: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set. Context: Observed when using python, macos - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_77f306218d1269b169d6fd1a5669ca47 | https://github.com/dottxt-ai/outlines/issues/1847 | TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set ## 22. 能力坑 · 失败模式：capability: [Feature] Streaming structured generation with partial validation - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: [Feature] Streaming structured generation with partial validation - 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature] Streaming structured generation with partial validation - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Streaming structured generation with partial validation. Context: Observed when using python - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_0990edf56e70825cebd4d6337f2e9ec7 | https://github.com/dottxt-ai/outlines/issues/1856 | [Feature] Streaming structured generation with partial validation ## 23. 能力坑 · 失败模式：capability: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation - 对用户的影响：Developers may hit a documented source-backed failure mode: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation. Context: Observed when using python - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_7477c33ba4e3aefcd5a822e817746461 | https://github.com/dottxt-ai/outlines/issues/1859 | 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation ## 24. 能力坑 · 失败模式：conceptual: Complex structure makes output empty - 严重度：low - 证据强度：source_linked - 发现：Developers should check this conceptual risk before relying on the project: Complex structure makes output empty - 对用户的影响：Developers may hit a documented source-backed failure mode: Complex structure makes output empty - 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。 - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_adb9b1e93b18abc454b9ec796b30af1a | https://github.com/dottxt-ai/outlines/issues/1861 | Complex structure makes output empty ## 25. 运行坑 · 失败模式：performance: [Feature Request] Add streaming support for structured generation - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: [Feature Request] Add streaming support for structured generation - 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Add streaming support for structured generation - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add streaming support for structured generation. Context: Observed when using python - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_issue | fmev_f9e262951793c35ca4f0f973546df68f | https://github.com/dottxt-ai/outlines/issues/1842 | [Feature Request] Add streaming support for structured generation ## 26. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作: issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | issue_or_pr_quality=unknown ## 27. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | release_recency=unknown ## 28. 维护坑 · 失败模式：maintenance: Outlines v1.2.12 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.12 - 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.12 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.12. Context: Observed when using docker - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_654aac443ea5eec7b12b4b1cbe602de9 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.13 | Outlines v1.2.12 ## 29. 维护坑 · 失败模式：maintenance: Outlines v1.2.9 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.9 - 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.9 - 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.9. Context: Source discussion did not expose a precise runtime context. - 防护动作: State this as source-backed community evidence, not as Doramagic reproduction. - 证据：failure_mode_cluster:github_release | fmev_e26ccdb4b7c8d266e55856497effd5ae | https://github.com/dottxt-ai/outlines/releases/tag/1.2.9 | Outlines v1.2.9