{
"canonical_name": "dottxt-ai/outlines",
"compilation_id": "pack_e3c36d6c5fe94d7b9a17b20b9aad811e",
"created_at": "2026-05-21T17:20:54.174821+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=prompt, recipe, host_instruction, eval, preflight",
"recommended_asset_types=prompt, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install outlines` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install outlines",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_6742779e1ab54c1781368925f35d8fa4"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_373c825fe18929b16c013d606104bf55",
"canonical_name": "dottxt-ai/outlines",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/dottxt-ai/outlines",
"slug": "outlines",
"source_packet_id": "phit_7cb79d12619d40d2b92d1beb3eb45251",
"source_validation_id": "dval_12464c5413314f709980a9b98f4740c4"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 698,
"github_stars": 13848,
"one_liner_en": "Structured Outputs",
"one_liner_zh": "Structured Outputs",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "outlines",
"title_zh": "outlines 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Automated Workflow",
"label_zh": "自动化工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-automated-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_7cb79d12619d40d2b92d1beb3eb45251",
"page_model": {
"artifacts": {
"artifact_slug": "outlines",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install outlines",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/dottxt-ai/outlines#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"自动化工作流",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Structured Outputs"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "prompt, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature] Streaming structured generation with partial validation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add more custom types",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add function calling and MCP support",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature Request] Add streaming support for structured generation",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes",
"category": "安装坑",
"evidence": [
"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"
],
"severity": "medium",
"suggested_check": "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",
"title": "失败模式：installation: Incompatibility with vllm==0.19 because of some api changes",
"user_impact": "Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes"
},
{
"body": "Developers should check this installation risk before relying on the project: Outlines v1.2.6",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.",
"title": "失败模式：installation: Outlines v1.2.6",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.2.6"
},
{
"body": "Developers should check this installation risk before relying on the project: Outlines v1.2.8",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python",
"title": "失败模式：installation: Outlines v1.2.8",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.2.8"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "Developers should check this migration risk before relying on the project: Outlines v1.2.10",
"category": "维护坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python",
"title": "失败模式：migration: Outlines v1.2.10",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.2.10"
},
{
"body": "Developers should check this migration risk before relying on the project: Outlines v1.3.0",
"category": "维护坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.",
"title": "失败模式：migration: Outlines v1.3.0",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.3.0"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Complex structure makes output empty",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 29 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] Streaming structured generation with partial validation。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 156,
"forks": 698,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 13848
},
"source_url": "https://github.com/dottxt-ai/outlines",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Structured Outputs",
"title": "outlines 能力包",
"trial_prompt": "# outlines - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 outlines 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Structured Outputs 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Outlines 简介。围绕“Outlines 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Outlines 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Outlines 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-core-concepts：Step 5 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/dottxt-ai/outlines\n- https://github.com/dottxt-ai/outlines#readme\n- README.md\n- outlines/release_note.md\n- pyproject.toml\n- environment.yml\n- examples/dating_profile.py\n- examples/react.py\n- outlines/generator.py\n- outlines/backends/__init__.py\n- outlines/processors/__init__.py\n- llm.txt\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 outlines 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Feature request: OWASP ASI06 memory poisoning defense for structured gen（https://github.com/dottxt-ai/outlines/issues/1864）；github/github_issue: [Feature Request] Add streaming support for structured generation（https://github.com/dottxt-ai/outlines/issues/1842）；github/github_issue: Add more custom types（https://github.com/dottxt-ai/outlines/issues/1303）；github/github_issue: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation（https://github.com/dottxt-ai/outlines/issues/1859）；github/github_issue: [Feature] Streaming structured generation with partial validation（https://github.com/dottxt-ai/outlines/issues/1856）；github/github_issue: Complex structure makes output empty（https://github.com/dottxt-ai/outlines/issues/1861）；github/github_issue: TransformerTokenizer reads attributes from raw backend that modern trans（https://github.com/dottxt-ai/outlines/issues/1847）；github/github_issue: Incompatibility with vllm==0.19 because of some api changes（https://github.com/dottxt-ai/outlines/issues/1854）；github/github_issue: Add function calling and MCP support（https://github.com/dottxt-ai/outlines/issues/1626）；github/github_release: Outlines v1.3.0（https://github.com/dottxt-ai/outlines/releases/tag/1.3.0）；github/github_release: Outlines v1.2.12（https://github.com/dottxt-ai/outlines/releases/tag/1.2.13）；github/github_release: Outlines v1.2.10（https://github.com/dottxt-ai/outlines/releases/tag/1.2.10）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Feature request: OWASP ASI06 memory poisoning defense for structured gen",
"url": "https://github.com/dottxt-ai/outlines/issues/1864"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request] Add streaming support for structured generation",
"url": "https://github.com/dottxt-ai/outlines/issues/1842"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add more custom types",
"url": "https://github.com/dottxt-ai/outlines/issues/1303"
},
{
"kind": "github_issue",
"source": "github",
"title": "📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation",
"url": "https://github.com/dottxt-ai/outlines/issues/1859"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature] Streaming structured generation with partial validation",
"url": "https://github.com/dottxt-ai/outlines/issues/1856"
},
{
"kind": "github_issue",
"source": "github",
"title": "Complex structure makes output empty",
"url": "https://github.com/dottxt-ai/outlines/issues/1861"
},
{
"kind": "github_issue",
"source": "github",
"title": "TransformerTokenizer reads attributes from raw backend that modern trans",
"url": "https://github.com/dottxt-ai/outlines/issues/1847"
},
{
"kind": "github_issue",
"source": "github",
"title": "Incompatibility with vllm==0.19 because of some api changes",
"url": "https://github.com/dottxt-ai/outlines/issues/1854"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add function calling and MCP support",
"url": "https://github.com/dottxt-ai/outlines/issues/1626"
},
{
"kind": "github_release",
"source": "github",
"title": "Outlines v1.3.0",
"url": "https://github.com/dottxt-ai/outlines/releases/tag/1.3.0"
},
{
"kind": "github_release",
"source": "github",
"title": "Outlines v1.2.12",
"url": "https://github.com/dottxt-ai/outlines/releases/tag/1.2.13"
},
{
"kind": "github_release",
"source": "github",
"title": "Outlines v1.2.10",
"url": "https://github.com/dottxt-ai/outlines/releases/tag/1.2.10"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Structured Outputs",
"effort": "安装已验证",
"forks": 698,
"icon": "code",
"name": "outlines 能力包",
"risk": "可发布",
"slug": "outlines",
"stars": 13848,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"自动化工作流",
"本地优先"
],
"thumb": "gray",
"type": "Prompt Preview"
},
"manual": {
"markdown": "# https://github.com/dottxt-ai/outlines 项目说明书\n\n生成时间: 2026-05-21 17:17:18 UTC\n\n## 目录\n\n- [Outlines 简介](#page-introduction)\n- [安装指南](#page-installation)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [核心概念](#page-core-concepts)\n- [输出类型](#page-output-types)\n- [类型系统](#page-type-system)\n- [模型提供者](#page-model-providers)\n- [生成器系统](#page-generator)\n- [后端系统](#page-backends)\n\n\n\n## Outlines 简介\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n \n\n# Outlines 简介\n\n## 项目概述\n\nOutlines 是一个用于引导大语言模型（LLM）生成结构化输出的开源框架。该项目由 .txt 团队开发和维护，旨在解决 LLM 输出不确定性这一核心问题。\n\n传统的 LLM 应用通常在生成后通过解析、正则表达式或脆弱的解析代码来尝试修复不良输出，这种方式容易出错且难以维护。Outlines 采用不同的方法：在生成过程中直接确保输出结构符合预期，从而从根本上保证输出的有效性。\n\n**核心价值主张：**\n\n- **结构保证**：在生成过程中直接约束输出格式，而非事后解析\n- **模型无关性**：同一套代码可在 OpenAI、Ollama、vLLM 等多种模型上运行\n- **类型安全**：通过 Python 类型系统直接指定输出类型\n- **提供商独立性**：切换模型时无需修改业务代码\n\n资料来源：[README.md:1-30]()\n\n## 核心特性\n\n### 支持的模型提供商\n\nOutlines 支持多种模型集成方式，形成统一的抽象接口：\n\n| 提供商类型 | 具体实现 | 异步支持 |\n|-----------|---------|---------|\n| 本地模型 | Transformers、VLLM、LlamaCpp、Ollama | 是 |\n| OpenAI 系列 | OpenAI、Azure OpenAI | 是 |\n| Anthropic 系列 | Claude 模型 | 是 |\n| Google 系列 | Gemini | 是 |\n| 其他 | SGLang、TGI、Transformers.js | 是 |\n\n异步模型包括 `AsyncSGLang`、`AsyncTGI`、`AsyncVLLM` 等，可通过以下方式初始化：\n\n```python\nimport outlines\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n资料来源：[README.md:60-80]()\n\n### 输出类型系统\n\nOutlines 的核心设计理念是让用户通过 Python 类型系统直接指定期望的输出结构：\n\n| 输出类型 | 定义方式 | 示例 |\n|---------|---------|-----|\n| 字面量类型 | `Literal` | `Literal[\"Yes\", \"No\"]` |\n| 数值类型 | Python 内置类型 | `int`、`float` |\n| 列表类型 | `list[T]` | `list[str]` |\n| 复杂对象 | Pydantic 模型 | `BaseModel` 子类 |\n| 正则约束 | Regex DSL | `Regex`、`String` |\n| JSON Schema | `JsonSchema` | `JsonSchema(schema_str)` |\n| 上下文无关文法 | `CFG` | CFG 语法定义 |\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass ProductReview(BaseModel):\n rating: Literal[\"poor\", \"fair\", \"good\", \"excellent\"]\n pros: list[str]\n cons: list[str]\n summary: str\n```\n\n资料来源：[outlines/release_note.md:30-60]()\n\n### 架构设计\n\nOutlines 采用分层架构设计，核心组件关系如下：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[模型调用层]\n B --> C[Generator 生成器]\n C --> D[输出类型编译]\n D --> E[Logits Processor]\n E --> F[底层模型推理]\n \n G[Transformers] --> F\n H[VLLM] --> F\n I[OpenAI] --> F\n J[Anthropic] --> F\n \n K[BaseModel] --> D\n L[Literal Type] --> D\n M[Regex DSL] --> D\n```\n\n#### 模型基类设计\n\n所有模型类继承自 `BaseModel`（异步）或 `BaseModel` 的变体，提供统一的调用接口：\n\n```mermaid\ngraph LR\n A[__call__] --> B[创建 Generator]\n C[batch] --> B\n D[stream] --> B\n B --> E[执行生成]\n \n F[type_adapter] -.-> A\n G[tensor_library_name] -.-> F\n```\n\n模型类必须定义 `type_adapter` 属性（类型 `ModelTypeAdapter`）和 `tensor_library_name` 属性。\n\n资料来源：[outlines/models/base.py:1-50]()\n\n## 快速开始指南\n\n### 安装\n\n```shell\npip install outlines\n```\n\n资料来源：[README.md:35-40]()\n\n### 基本使用流程\n\n```mermaid\ngraph LR\n A[安装 Outlines] --> B[加载模型]\n B --> C[定义输出类型]\n C --> D[调用模型生成]\n D --> E[获取结构化输出]\n```\n\n### 第一步：连接模型\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n资料来源：[README.md:42-55]()\n\n### 第二步：简单分类任务\n\n```python\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n```\n\n资料来源：[README.md:56-65]()\n\n### 第三步：数值提取\n\n```python\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n```\n\n资料来源：[README.md:66-70]()\n\n### 第四步：复杂结构\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n\nreview = model(\n \"Write a review for the iPhone 15 Pro\",\n ProductReview\n)\n```\n\n资料来源：[README.md:71-90]()\n\n## Generator 生成器\n\nGenerator 是 Outlines v1 版本引入的核心组件，用于封装模型和输出类型的组合。\n\n### 设计目的\n\nGenerator 的主要价值在于**可重用性**和**编译缓存**：\n\n| 特性 | 说明 |\n|-----|------|\n| 可重用性 | 无需每次调用时指定输出类型 |\n| 编译缓存 | 输出类型的编译（当适用时）仅执行一次 |\n| 批处理支持 | 同一 Generator 可处理多个输入 |\n\n### 基本用法\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n age: int\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 创建 Generator\ngenerator = Generator(model, Character)\n\n# 多次调用，输出类型无需重复指定\nresult1 = generator(\"Create a young wizard character\")\nresult2 = generator(\"Create an old warrior character\")\n```\n\n### Generator 方法\n\n| 方法 | 描述 | 异步版本 |\n|-----|------|---------|\n| `__call__` | 单次生成 | `async def __call__` |\n| `batch` | 批量生成 | `async def batch` |\n| `stream` | 流式生成 | `async def stream` |\n\n资料来源：[outlines/models/base.py:50-120]()\n\n## 正则表达式 DSL\n\nOutlines 提供了正则表达式领域特定语言（Regex DSL），允许通过代码组合构建复杂的正则模式。\n\n### 可用组件\n\n| 组件 | 功能 | 示例 |\n|-----|------|-----|\n| `Regex` | 匹配正则表达式 | `Regex(r\"[0-9]+\")` |\n| `String` | 匹配字符串字面量 | `String(\"yes\")` |\n| `either` | 或运算 | `either(a, b)` |\n| `optional` | 可选修饰 | `optional(pattern)` |\n| `at_least` | 至少重复次数 | `at_least(n, pattern)` |\n| `integer` | 匹配整数 | `integer()` |\n\n### 使用示例\n\n```python\nfrom outlines.types import at_least, either, integer, optional\n\n# 构建复杂模式\npattern = either(\n integer(),\n at_least(2, String(\"ab\"))\n)\n```\n\n### JsonSchema 类型\n\n`JsonSchema` 是一个独立的 Term，可直接用作输出类型：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2? Respond in a json\", JsonSchema(json_schema))\n```\n\n资料来源：[outlines/release_note.md:60-90]()\n\n## 异常处理体系\n\nOutlines 定义了完整的异常层次结构，便于应用程序进行错误处理。\n\n### 异常层次\n\n```mermaid\ngraph TD\n A[Exception] --> B[OutlinesError]\n B --> C[APIError]\n C --> D[AuthenticationError]\n C --> E[PermissionDeniedError]\n C --> F[NotFoundError]\n C --> G[RateLimitError]\n C --> H[BadRequestError]\n C --> I[ServerError]\n C --> J[APITimeoutError]\n C --> K[APIConnectionError]\n B --> L[ProviderResponseError]\n B --> M[GenerationError]\n```\n\n### APIError 核心属性\n\n| 属性 | 类型 | 说明 |\n|-----|------|------|\n| `provider` | `str \\| None` | 提供商名称，如 `\"openai\"` |\n| `original_exception` | `Exception \\| None` | 原始 SDK 异常 |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 提供商请求 ID |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 人类可读的建议信息 |\n\n### 错误处理示例\n\n```python\nfrom outlines.exceptions import APIError, RateLimitError, normalize_provider_errors\n\ntry:\n with normalize_provider_errors(provider=\"openai\"):\n result = model(\"Generate something\", str)\nexcept RateLimitError as e:\n print(f\"Rate limited: {e.hint}\")\nexcept APIError as e:\n print(f\"API Error: {e.request_id}\")\n```\n\n资料来源：[outlines/exceptions.py:1-60]()\n\n## 版本迁移指南\n\n### v0 到 v1 重要变更\n\n#### 移除的功能\n\n| 旧功能 | 替代方案 | 说明 |\n|-------|---------|------|\n| `Function` 类 | `Application` 类 | Application 不在初始化时绑定模型 |\n| `Template.from_file` | `Template.from_string` + 文件读取 | 简化模板加载逻辑 |\n| Exllamav2 模型 | 无替代 | 接口不兼容，已移除 |\n| `load_lora` 方法 | LoRA 请求参数 | 通过 `lora_request` 参数传递 |\n\n#### Function 到 Application 迁移\n\n```python\n# v0 写法（已废弃）\nfrom outlines import Function, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\nfn = Function(template, Character, \"hf-internal-testing/tiny-random-GPTJForCausalLM\")\nresponse = fn(gender=\"female\")\n\n# v1 写法（推荐）\nfrom outlines import Application, Template\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\nresponse = app(model, {\"gender\": \"female\"})\n```\n\n#### LoRA 加载变更\n\n```python\n# v0 写法（已废弃）\nmodel.load_lora(\"path/to/lora/file\")\n\n# v1 写法（推荐）\nfrom vllm.lora.request import LoRARequest\n\nlora_request = LoRARequest(\"my_lora\", 1, \"path/to/lora/file\")\nresponse = model(\"Write a short story\", str, lora_request=lora_request)\n```\n\n资料来源：[outlines/release_note.md:1-40]()\n\n### 模型调用方式变化\n\nv1 版本支持直接调用模型，无需先创建生成器：\n\n```python\n# 方式一：直接调用（v1 新增）\nresult = model(\"Write a story\", str, max_tokens=100)\n\n# 方式二：使用 Generator（v1 新增）\ngenerator = Generator(model, str)\nresult = generator(\"Write a story\", max_tokens=100)\n```\n\n两种方式等效，Generator 的优势在于可重用性和编译缓存。\n\n资料来源：[outlines/release_note.md:100-120]()\n\n## 应用示例\n\n### 客户服务工单分类\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass ServiceTicket(BaseModel):\n category: Literal[\"billing\", \"technical\", \"shipping\", \"general\"]\n priority: Literal[\"low\", \"medium\", \"high\", \"urgent\"]\n summary: str\n requires_manager: bool\n\nticket = model(prompt, ServiceTicket, max_new_tokens=500)\n\n# 根据结果路由\nif ticket.priority == \"urgent\" or ticket.requires_manager:\n alert_manager(ticket)\n```\n\n### 产品分类\n\n```python\nfrom pydantic import BaseModel\nfrom typing import List, Optional\n\nclass ProductCategory(BaseModel):\n main_category: str\n sub_category: str\n attributes: List[str]\n brand_match: Optional[str]\n\n# 处理产品描述\nproduct = \"Apple iPhone 15 Pro, 256GB, Titanium Gray\"\nresult = model(product, ProductCategory)\n```\n\n### 会议安排\n\n```python\nfrom typing import List, Optional\nfrom datetime import date\n\ndef schedule_meeting(\n title: str,\n date: date,\n duration_minutes: int,\n attendees: List[str],\n location: Optional[str] = None,\n agenda_items: Optional[List[str]] = None\n):\n # 实际应用中创建会议\n meeting = {\n \"title\": title,\n \"date\": date,\n \"duration_minutes\": duration_minutes,\n \"attendees\": attendees,\n }\n return f\"Meeting '{title}' scheduled\"\n\nresult = model(natural_language_request, schedule_meeting)\n```\n\n资料来源：[README.md:100-180]()\n\n## 部署选项\n\n### Modal 部署\n\nOutlines 支持在 Modal 平台上部署：\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n```\n\n资料来源：[examples/modal_example.py:1-20]()\n\n### BentoML 部署\n\n```python\n# requirements.txt\nbentoml>=1.2.11\noutlines==0.0.37\ntransformers==4.38.2\ndatasets==2.18.0\naccelerate==0.27.2\n```\n\n资料来源：[examples/bentoml/requirements.txt:1-5]()\n\n## 核心设计原则\n\nOutlines 的设计遵循以下原则：\n\n| 原则 | 描述 | 实现方式 |\n|-----|------|---------|\n| 类型即约束 | 期望输出通过类型指定 | Pydantic、Literal、int 等 |\n| 生成时验证 | 结构在生成过程中保证 | Logits Processor |\n| 模型抽象 | 统一接口支持多模型 | BaseModel 基类 |\n| 异步优先 | 完整异步支持 | AsyncModel 基类 |\n| 渐进式复杂度 | 从简单到复杂逐步深入 | 多种输出类型选项 |\n\n**类型即约束**的设计哲学与 Python 自身的类型系统保持一致，使得开发者可以像定义函数返回类型一样定义 LLM 输出的期望结构。\n\n资料来源：[README.md:20-35]()\n\n## 总结\n\nOutlines 是一个功能强大且设计优雅的结构化输出框架，通过以下核心能力解决了 LLM 应用开发中的关键挑战：\n\n1. **生成时结构保证**：避免生成后解析的不确定性和脆弱性\n2. **统一的模型接口**：支持多种提供商，切换模型无需修改业务代码\n3. **Pythonic 类型系统**：利用 Python 原生类型指定输出结构\n4. **灵活的输出约束**：支持 Literal、Pydantic、Regex、JSON Schema 等多种约束方式\n5. **完整的异步支持**：适配现代异步应用架构\n6. **清晰的异常层次**：便于错误处理和调试\n\nOutlines v1 版本通过引入 Generator 组件、异步模型支持和完善的类型系统，进一步提升了框架的可用性和灵活性，使其成为构建生产级 LLM 应用的理想选择。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[Outlines 简介](#page-introduction), [快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/dottxt-ai/outlines/blob/main/pyproject.toml)\n- [environment.yml](https://github.com/dottxt-ai/outlines/blob/main/environment.yml)\n- [examples/bentoml/requirements.txt](https://github.com/dottxt-ai/outlines/blob/main/examples/bentoml/requirements.txt)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n \n\n# 安装指南\n\n## 概述\n\nOutlines 是一个用于大语言模型（LLM）结构化输出的 Python 库。本指南将帮助用户在各种环境中正确安装和配置 Outlines。\n\n## 系统要求\n\n### Python 版本\n\nOutlines 需要 Python 3.10 或更高版本。\n\n```资料来源：[examples/modal_example.py:1]()[examples/bentoml/requirements.txt:4]()\n\n依赖项版本兼容性：\n- Python ≥ 3.10\n- outlines ≥ 1.0.0\n\n```\n\n## 安装方法\n\n### 使用 pip 安装（推荐）\n\n通过 pip 安装 Outlines 是最简单的方式：\n\n```bash\npip install outlines\n```\n\n资料来源：[README.md:1]()\n\n### 从源码安装\n\n对于需要最新功能或想要参与开发的用户，可以从源码安装：\n\n```bash\ngit clone https://github.com/dottxt-ai/outlines.git\ncd outlines\npip install -e .\n```\n\n## 核心依赖\n\nOutlines 的核心功能依赖于以下库：\n\n| 依赖项 | 用途 | 最低版本 |\n|--------|------|----------|\n| pydantic | 数据验证和结构定义 | - |\n| interegular | 正则表达式处理和 FSM 编译 | - |\n| numpy | 数值计算支持 | - |\n\n资料来源：[pyproject.toml](https://github.com/dottxt-ai/outlines/blob/main/pyproject.toml)\n\n## 模型后端安装\n\nOutlines 支持多种模型后端，不同的后端需要不同的依赖配置。\n\n### Transformers 后端\n\n用于本地 Hugging Face 模型，需要安装 transformers 和相关依赖：\n\n```资料来源：[README.md:1]()\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n依赖版本要求：\n```\ntransformers>=4.38.2\ndatasets>=2.18.0\naccelerate>=0.27.2\n```\n\n资料来源：[examples/bentoml/requirements.txt:3-5]()\n\n### vLLM 后端\n\n用于高效的推理服务部署：\n\n```python\nfrom outlines import from_vllm\nfrom vllm import LLM\n\nmodel = from_vllm(LLM(\"microsoft/Phi-3-mini-4k-instruct\"))\n```\n\n安装 vLLM 后端需要单独的 vLLM 库：\n\n```bash\npip install vllm\n```\n\n### OpenAI API 后端\n\n用于调用 OpenAI API 模型：\n\n```python\nimport outlines\n\nmodel = outlines.openai(\"gpt-4\")\nresult = model(\"Hello world\", str)\n```\n\n### Anthropic API 后端\n\n用于调用 Anthropic Claude 模型：\n\n```python\nimport outlines\n\nmodel = outlines.anthropic(\"claude-3-opus-20240229\")\nresult = model(\"Hello world\", str)\n```\n\n### Ollama 后端\n\n用于调用本地 Ollama 模型：\n\n```python\nfrom huggingface_hub import AsyncInferenceClient\nimport outlines\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n## 环境配置\n\n### 使用 conda 环境\n\n可以通过 environment.yml 创建完整的环境：\n\n```yaml\nname: outlines-env\ndependencies:\n - python>=3.10\n - pip\n - pip:\n - outlines\n - transformers\n - accelerate\n```\n\n创建环境命令：\n\n```bash\nconda env create -f environment.yml\nconda activate outlines-env\n```\n\n资料来源：[environment.yml](https://github.com/dottxt-ai/outlines/blob/main/environment.yml)\n\n### GPU 环境配置\n\n对于使用 GPU 进行推理的模型，需要配置 CUDA 环境：\n\n1. 确保安装 NVIDIA 驱动\n2. 安装对应版本的 CUDA Toolkit\n3. 安装 PyTorch with CUDA 支持：\n\n```bash\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121\n```\n\n## Docker 部署\n\n### 使用 Modal 部署\n\nOutlines 支持通过 Modal 进行云端部署：\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n```\n\n资料来源：[examples/modal_example.py:7-12]()\n\n### BentoML 部署\n\nOutlines 也可以通过 BentoML 进行容器化部署：\n\n依赖要求：\n```\nbentoml>=1.2.11\noutlines==0.0.37\ntransformers==4.38.2\ndatasets>=2.18.0\naccelerate>=0.27.2\n```\n\n资料来源：[examples/bentoml/requirements.txt:1-5]()\n\n## 安装验证\n\n安装完成后，可以通过以下方式验证：\n\n```python\nimport outlines\nfrom outlines import from_transformers\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n# 验证基本导入\nprint(\"Outlines 版本:\", outlines.__version__)\n\n# 验证模型加载（使用最小模型示例）\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 测试结构化输出\nfrom typing import Literal\nresult = model(\"Pizza or burger?\", Literal[\"pizza\", \"burger\"])\nprint(f\"结果: {result}\")\n```\n\n## 常见问题\n\n### 依赖冲突\n\n如果遇到依赖冲突，建议：\n\n1. 创建独立的虚拟环境\n2. 使用 `pip install --upgrade` 更新相关包\n3. 检查 Python 版本是否满足要求\n\n### CUDA 版本不兼容\n\n确保 PyTorch 版本与 CUDA 版本匹配：\n\n| CUDA 版本 | PyTorch 最低版本 |\n|-----------|------------------|\n| CUDA 11.7 | torch >= 1.13 |\n| CUDA 11.8 | torch >= 2.0 |\n| CUDA 12.1 | torch >= 2.1 |\n\n### 模型下载失败\n\n如果模型下载失败，可以：\n\n1. 设置 Hugging Face 镜像源\n2. 预先下载模型到本地目录\n3. 使用离线模式加载已缓存的模型\n\n## 版本升级\n\n### 从旧版本升级\n\n从 v0.x 升级到 v1.x 需要注意以下重大变更：\n\n| v0.x 特性 | v1.x 等效 |\n|-----------|-----------|\n| `Generator` | `Generator` 或直接调用模型 |\n| `Function` | `Application` |\n| `load_lora()` | 通过模型实例或参数传递 |\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n升级步骤：\n\n```bash\npip install --upgrade outlines\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|pip| C[pip install outlines]\n B -->|conda| D[conda env create]\n B -->|源码| E[git clone && pip install -e]\n C --> F{需要模型后端?}\n D --> F\n E --> F\n F -->|Transformers| G[安装 transformers/accelerate]\n F -->|vLLM| H[安装 vllm]\n F -->|API| I[安装 openai/anthropic SDK]\n F -->|无后端| J[仅核心功能]\n G --> K[验证安装]\n H --> K\n I --> K\n J --> K\n K --> L{验证成功?}\n L -->|是| M[安装完成]\n L -->|否| N[排查问题]\n N --> K\n```\n\n## 相关文档\n\n- [快速入门指南](README.md)\n- [模型集成](../features/models)\n- [核心功能](../features/core/generator)\n- [结构化输出类型](../features/core/ouput_types)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[Outlines 简介](#page-introduction), [输出类型](#page-output-types)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [release_note.md](https://github.com/dottxt-ai/outlines/blob/main/release_note.md)\n- [examples/dating_profile.py](https://github.com/dottext-ai/outlines/blob/main/examples/dating_profile.py)\n- [examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n \n\n# 快速开始\n\nOutlines 是一个用于在大型语言模型（LLM）生成过程中保证结构化输出的 Python 库。本页面将指导您从安装到完成第一个结构化生成任务，帮助您快速上手 Outlines 的核心功能。\n\n## 安装 Outlines\n\n### 使用 pip 安装\n\n通过 pip 安装 Outlines 的稳定版本：\n\n```shell\npip install outlines\n```\n\n资料来源：[README.md:1]()\n\n### 安装特定版本（可选）\n\n如需安装特定版本，可以使用版本号：\n\n```shell\npip install outlines==1.0.0\n```\n\n资料来源：[examples/modal_example.py:14]()\n\n## 连接模型\n\nOutlines 支持多种模型后端，包括 Transformers、OpenAI、Anthropic、Ollama、vLLM 等。以下介绍最常用的 Transformers 集成方式。\n\n### 使用 Transformers 模型\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n资料来源：[README.md:1]()\n\n### 从 v0 到 v1 的 API 变化\n\n在 v1 版本中，模型创建方式发生了重要变化：\n\n```python\n# v0 方式\nfrom outlines import models\nmodel = models.transformers(\"microsoft/Phi-3-mini-4k-instruct\")\n\n# v1 方式\nfrom outlines import from_transformers\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n```\n\n资料来源：[release_note.md:1]()\n\n## 基本结构化输出\n\nOutlines 的核心理念是直接指定输出类型，系统自动保证生成结果符合该结构。\n\n### 简单分类任务\n\n使用 `Literal` 类型进行分类：\n\n```python\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # 输出: \"Positive\"\n```\n\n资料来源：[README.md:1]()\n\n### 数值类型输出\n\n直接指定 Python 内置类型：\n\n```python\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 输出: 100\n```\n\n资料来源：[README.md:1]()\n\n## 使用 Pydantic 模型\n\n对于复杂的数据结构，使用 Pydantic 定义模型：\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n```\n\n资料来源：[README.md:1]()\n\n### 完整示例：约会资料生成\n\n以下是一个完整的结构化输出示例：\n\n```python\nimport outlines\nfrom pydantic import BaseModel\nfrom typing import Optional, List\nfrom enum import Enum\n\n\nclass MbtiType(str, Enum):\n INTJ = \"INTJ\"\n INFP = \"INFP\"\n ENTP = \"ENTP\"\n # ... 其他 MBTI 类型\n\n\nclass HobbyCategory(str, Enum):\n sports = \"sports\"\n arts = \"arts\"\n gaming = \"gaming\"\n outdoors = \"outdoors\"\n music = \"music\"\n reading = \"reading\"\n cooking = \"cooking\"\n travel = \"travel\"\n\n\nclass DatingProfile(BaseModel):\n name: str\n age: int\n gender: str\n mbti: MbtiType\n location: str\n height: int\n bio: str\n hobbies: List[HobbyCategory]\n preferred_gender: str\n preferred_age_range: str\n personality_traits: List[str]\n\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n\nprofile = model(\"Create a dating profile for a 28-year-old software engineer in San Francisco\", DatingProfile)\nprint(profile)\n```\n\n资料来源：[examples/dating_profile.py:1]()\n\n## 使用模板\n\nOutlines 支持 Jinja 模板，便于动态生成提示词：\n\n```python\nimport outlines\n\n# 从字符串创建模板\nsentiment_template = outlines.Template.from_string(\"\"\"\n<|im_start|>user\nAnalyze the sentiment of the following {{ content_type }}:\n\n{{ text }}\n\nProvide your analysis as either \"Positive\", \"Negative\", or \"Neutral\".\n<|im_end>\n<|im_start|>assistant\n\"\"\")\n\n# 使用模板生成提示词\nreview = \"This restaurant exceeded all my expectations. Fantastic service!\"\nprompt = sentiment_template(content_type=\"review\", text=review)\n\n# 使用模板进行结构化生成\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md:1]()\n\n### 从文件加载模板\n\n```python\n# 从文件加载模板\nexample_template = outlines.Template.from_file(\"templates/few_shot.txt\")\n```\n\n资料来源：[README.md:1]()\n\n## ReAct 模式\n\nOutlines 支持 ReAct（Reasoning + Acting）模式，实现链式推理和工具调用：\n\n```python\ndef search_wikipedia(query: str) -> str:\n \"\"\"模拟 Wikipedia 搜索\"\"\"\n # 实际实现中会调用 Wikipedia API\n return f\"Results for: {query}\"\n\ndef add_mode(i: int, mode: str, result: str, prompt: str) -> str:\n \"\"\"添加观察结果到提示词\"\"\"\n return prompt + f\"\\n{i}. {mode}: {result}\\n\"\n\n# 初始化\nprompt = \"Apple Computers\"\nmode = \"Thought\"\n\n# ReAct 循环\nfor i in range(3):\n thought = _generator(prompt, stop=[\"'\"], max_tokens=128)\n \n if \"Search\" in thought:\n subject = \" \".join(thought.split()[:2])\n result = search_wikipedia(subject)\n prompt = add_mode(i=i, mode=\"Obs\", result=result, prompt=prompt)\n else:\n break\n```\n\n资料来源：[examples/react.py:1]()\n\n## 生成器模式\n\n使用 `Generator` 类可以创建可重用的生成器，避免重复编译：\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 创建生成器\ngenerator = Generator(model, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n\n# 多次使用，无需重复指定输出类型\nresult1 = generator(\"This movie was amazing!\")\nresult2 = generator(\"The food was terrible.\")\n```\n\n资料来源：[release_note.md:1]()\n\n## 完整工作流程图\n\n```mermaid\ngraph TD\n A[安装 Outlines] --> B[选择模型后端]\n B --> C{模型类型}\n C -->|Transformers| D[使用 from_transformers]\n C -->|OpenAI| E[使用 from_openai]\n C -->|vLLM| F[使用 from_vllm]\n D --> G[定义输出类型]\n E --> G\n F --> G\n G --> H{复杂度}\n H -->|简单类型| I[使用 Literal 或内置类型]\n H -->|复杂结构| J[使用 Pydantic 模型]\n I --> K[调用 model 生成]\n J --> K\n K --> L[获得结构化输出]\n```\n\n## 快速参考表\n\n| 场景 | 输出类型 | 示例 |\n|------|----------|------|\n| 二分类 | `Literal[\"Yes\", \"No\"]` | 情感判断 |\n| 多分类 | `Literal[\"A\", \"B\", \"C\"]` | 主题分类 |\n| 整数 | `int` | 数量提取 |\n| 浮点数 | `float` | 温度提取 |\n| 复杂对象 | `BaseModel` | JSON 结构 |\n\n## 常见问题\n\n### 模型调用方式变化\n\nv1 版本支持直接调用模型，无需先创建生成器：\n\n```python\n# v1 直接调用\nresult = model(\"prompt\", output_type)\n\n# 或使用生成器（推荐重复使用场景）\ngenerator = Generator(model, output_type)\nresult = generator(\"prompt\")\n```\n\n### JSON Schema 支持\n\n可以使用 `JsonSchema` 类型直接指定 JSON Schema：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2? Respond in a json\", JsonSchema(json_schema))\n```\n\n资料来源：[release_note.md:1]()\n\n## 下一步\n\n- 阅读[安装指南](./guide/installation.md)了解更详细的安装选项\n- 查看[架构文档](./guide/architecture.md)深入了解 Outlines 工作原理\n- 探索[功能文档](./features/index.md)学习更多高级用法\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心概念](#page-core-concepts), [后端系统](#page-backends)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/processors/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/processors/__init__.py)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n \n\n# 系统架构\n\n## 概述\n\nOutlines 是一个保证大型语言模型（LLM）输出结构化的框架。其核心设计理念是通过类型驱动的 API，让用户在调用模型时直接指定期望的输出类型（如 `Literal[\"Yes\", \"No\"]`、`int` 或 Pydantic 模型），Outlines 会在生成过程中强制保证输出符合该结构。\n\n该框架的核心价值在于**生成时约束**（而不是生成后解析），这避免了传统方法中依赖正则表达式或脆弱解析逻辑所带来的问题。\n\n资料来源：[README.md]()\n\n## 架构分层\n\nOutlines 采用分层架构设计，各层职责清晰，从用户 API 到底层模型提供者形成单向依赖关系：\n\n```mermaid\ngraph TD\n A[用户 API
outlines.models] --> B[生成器类
SteerableGenerator
BlackBoxGenerator]\n B --> C[类型系统
types/dsl.py
Pydantic → JsonSchema → Regex]\n C --> D[FSM 编译
outlines-core
regex → FSM via interegular]\n D --> E[引导系统
processors/guide.py
FSM 状态管理]\n E --> F[Logits 处理
processors/structured.py
Token 掩码]\n F --> G[模型提供者
transformers
OpenAI
vLLM
Ollama]\n```\n\n资料来源：[llm.txt]()\n\n### 层级职责说明\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 用户 API | `outlines.models` | 提供统一的模型调用接口 |\n| 生成器 | `Generator`, `SteerableGenerator`, `BlackBoxGenerator` | 管理生成逻辑和输出类型编译 |\n| 类型系统 | `types/dsl.py` | 将 Python 类型转换为内部表示 |\n| FSM 编译 | `outlines-core` | 将正则表达式编译为有限状态机 |\n| 引导系统 | `processors/guide.py` | 管理 FSM 状态和有效 Token |\n| Logits 处理 | `processors/structured.py` | 通过 Token 掩码强制约束 |\n| 模型提供者 | transformers, OpenAI 等 | 与具体模型 API 交互 |\n\n资料来源：[llm.txt]()\n\n## 核心组件\n\n### 模型层 (`outlines/models/`)\n\n#### 模型基类设计\n\n模型层包含两个核心基类，分别对应不同类型的模型：\n\n| 基类 | 适用场景 | 控制方式 |\n|------|----------|----------|\n| `SteerableModel` | 本地模型（transformers, llama.cpp） | 直接控制 logits |\n| `BlackBoxModel` | API 模型（OpenAI, Anthropic） | 利用提供商的原生结构化输出支持 |\n\n#### 异步支持\n\nv1.0 版本新增了对异步操作的支持，新增了三个异步模型类：\n\n- `AsyncSGLang`\n- `AsyncTGI`\n- `AsyncVLLM`\n\n```python\nfrom outlines import from_tgi\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n资料来源：[outlines/release_note.md]()\n\n#### 异步方法接口\n\n所有模型类都实现了以下异步方法：\n\n| 方法 | 功能 | 返回类型 |\n|------|------|----------|\n| `async stream(...)` | 异步流式生成 | `AsyncIterator[Any]` |\n| `async batch(...)` | 异步批量生成 | `List[Any]` |\n| `async __call__(...)` | 异步单次调用 | `Any` |\n\n```python\n# 流式调用等效方式\ngenerator = Generator(model, Foo)\nasync for chunk in generator(\"prompt\"):\n print(chunk)\n\n# 直接调用模型\nasync for chunk in model.stream(\"prompt\", Foo):\n print(chunk)\n\n# 等效的异步调用\nawait model(\"prompt\", Foo)\n```\n\n资料来源：[outlines/models/base.py]()\n\n### 生成器层\n\n#### Generator 类\n\n`Generator` 是 Outlines v1.0 引入的核心组件，用于封装模型和输出类型的组合：\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ngenerator = Generator(model, int)\nresult = generator(\"What's 2 + 2?\")\n```\n\n生成器的优势在于：\n- **可复用性**：无需每次调用都指定输出类型\n- **延迟编译**：输出类型的 FSM 编译只在首次使用时执行一次\n- **持久缓存**：编译结果会被缓存\n\n资料来源：[outlines/release_note.md]()\n\n#### 生成器类型\n\n| 类型 | 适用模型 | 约束实现方式 |\n|------|----------|--------------|\n| `SteerableGenerator` | 本地模型 | FSM + Logits 掩码 |\n| `BlackBoxGenerator` | API 模型 | 提供商原生结构化输出 |\n\n### 类型系统\n\n类型系统负责将 Python 类型转换为内部约束表示：\n\n```mermaid\ngraph LR\n A[Python 类型] --> B[Pydantic 模型]\n A --> C[Literal 类型]\n A --> D[JsonSchema]\n A --> E[Regex/CFG]\n B --> F[JsonSchema]\n C --> G[正则表达式]\n D --> G\n E --> G\n F --> H[FSM]\n G --> H\n```\n\n#### 支持的类型格式\n\n| 类型格式 | 示例 | 说明 |\n|----------|------|------|\n| `Literal` | `Literal[\"Yes\", \"No\"]` | 枚举值约束 |\n| `int` / `float` | `int` | 数值类型约束 |\n| `Pydantic` | `BaseModel` 子类 | 复杂对象结构 |\n| `JsonSchema` | `{\"type\": \"object\", ...}` | JSON Schema 格式 |\n| `Regex` | `Regex(r\"\\d+\")` | 正则表达式约束 |\n| `CFG` | 上下文无关文法 | 形式文法约束 |\n\n资料来源：[outlines/release_note.md]()\n\n### FSM 编译层\n\nFSM（有限状态机）是 Outlines 实现结构化生成的核心机制：\n\n```mermaid\ngraph LR\n A[正则表达式] -->|interegular| B[FSM]\n B --> C[状态转换表]\n C --> D[有效 Token 集合]\n```\n\n**工作流程**：\n1. 用户指定输出类型（如 `Literal[\"Yes\", \"No\"]`）\n2. 类型系统将其转换为正则表达式\n3. 正则表达式通过 `interegular` 库编译为 FSM\n4. FSM 在生成过程中追踪有效状态\n\n资料来源：[llm.txt]()\n\n### 引导系统 (`processors/guide.py`)\n\n引导系统负责管理 FSM 状态并计算每个时间步的有效 Token：\n\n```mermaid\ngraph TD\n A[当前 Token] --> B[FSM 状态更新]\n B --> C{终止状态?}\n C -->|是| D[停止生成]\n C -->|否| E[计算有效 Token]\n E --> F[掩码 Logits]\n F --> G[采样下一 Token]\n G --> A\n```\n\n关键特性：\n- **Token 级控制**：约束作用于 Token 级别，而非字符级别\n- **状态追踪**：维护 FSM 的当前状态\n- **动态掩码**：根据有效 Token 集合屏蔽无效 Token\n\n资料来源：[llm.txt]()\n\n### 异常处理 (`outlines/exceptions.py`)\n\nOutlines 定义了完整的异常层次结构：\n\n```mermaid\ngraph TD\n A[Exception] --> B[OutlinesError]\n B --> C[APIError]\n C --> D[AuthenticationError]\n C --> E[PermissionDeniedError]\n C --> F[NotFoundError]\n C --> G[RateLimitError]\n C --> H[BadRequestError]\n C --> I[ServerError]\n C --> J[APITimeoutError]\n C --> K[APIConnectionError]\n B --> L[ProviderResponseError]\n B --> M[GenerationError]\n```\n\n#### 异常类属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `provider` | `str \\| None` | 提供商名称（如 \"openai\"） |\n| `original_exception` | `Exception \\| None` | 原始 SDK 异常 |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 请求 ID（用于问题追踪） |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 人类可读的建议信息 |\n\n资料来源：[outlines/exceptions.py]()\n\n## 关键设计决策\n\n### 1. FSM 基础约束\n\n对于本地模型，约束被编译为有限状态机，用于追踪有效下一个 Token。这种方法确保了生成过程严格遵守结构规范。\n\n资料来源：[llm.txt]()\n\n### 2. 提供商抽象\n\n统一的约束系统同时支持本地模型（transformers）和 API 模型（OpenAI）。对于 API 模型，Outlines 会利用提供商原生的结构化输出功能（如 OpenAI 的 JSON Mode）。\n\n资料来源：[README.md]()\n\n### 3. 延迟编译\n\nFSM 在首次使用时编译并持久缓存，避免了重复编译的开销。\n\n```python\n# 首次调用时编译 FSM\nresult = model(\"What's 2 + 2?\", int) # 编译发生在此时\n\n# 后续调用使用缓存\nresult = model(\"What's 3 + 3?\", int) # 使用缓存的 FSM\n```\n\n资料来源：[outlines/release_note.md]()\n\n### 4. 类型驱动 API\n\nPython 类型是指定约束的主要接口，与 Python 自身的类型系统保持一致：\n\n| 需求 | 类型指定方式 |\n|------|--------------|\n| 是/否回答 | `Literal[\"Yes\", \"No\"]` |\n| 数值 | `int` |\n| 复杂对象 | Pydantic 模型 |\n\n资料来源：[README.md]()\n\n## 模型集成\n\n### 支持的模型提供商\n\n| 提供商 | 模型类 | 特点 |\n|--------|--------|------|\n| Transformers | `Transformers` | 本地模型，完整控制 |\n| OpenAI | `OpenAI` | API 调用 |\n| Anthropic | `Anthropic` | API 调用 |\n| Ollama | `Ollama` | 本地模型 |\n| vLLM | `VLLM` | 高性能本地推理 |\n| SGLang | `SGLang` | 高性能本地推理 |\n| TGI | `TGI` | Hugging Face 推理端点 |\n| Llama.cpp | `LlamaCpp` | CPU 高效推理 |\n| Gemini | `Gemini` | Google AI 模型 |\n\n### 模型初始化示例\n\n```python\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\", device_map=\"auto\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"Analyze: 'Great product!'\", Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md]()\n\n## LoRA 支持变化\n\nv1.0 版本对 LoRA 加载方式进行了调整：\n\n| 版本 | 方式 | 示例 |\n|------|------|------|\n| v0 | `model.load_lora(path)` | 直接在模型上调用 |\n| v1 | 参数传递 | `response = model(..., lora_request=lora_request)` |\n\n```python\nfrom outlines import from_vllm\nfrom vllm import LLM\nfrom vllm.lora.request import LoRARequest\n\nmodel = from_vllm(LLM(\"microsoft/Phi-3-mini-4k-instruct\"))\nlora_request = LoRARequest(\"lora_name\", 1, \"path/to/lora/file\")\nresponse = model(\"Write a short story.\", lora_request=lora_request)\n```\n\n资料来源：[outlines/release_note.md]()\n\n## 弃用说明\n\n### v1.0 弃用的功能\n\n| 组件 | 替代方案 | 原因 |\n|------|----------|------|\n| `Exllamav2` 模型 | 无替代 | 接口不兼容，维护成本高 |\n| `Function` 类 | `Application` 类 | 更清晰的职责分离 |\n| `Generator.load_lora()` | 模型初始化参数或调用参数 | 统一的 LoRA 管理方式 |\n\n#### Function 到 Application 的迁移\n\n```python\n# v0\nfrom outlines import Function, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\nfn = Function(template, Character, \"hf-internal-testing/tiny-random-GPTJForCausalLM\")\nresponse = fn(gender=\"female\")\n\n# v1\nfrom outlines import Application, Template, from_transformers\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\nresponse = app(model, {\"gender\": \"female\"})\n```\n\n资料来源：[outlines/release_note.md]()\n\n## 总结\n\nOutlines 的系统架构通过分层设计实现了灵活且强大的结构化生成能力：\n\n1. **统一 API**：用户通过简单的类型指定即可约束输出\n2. **高效编译**：延迟编译和持久缓存优化性能\n3. **广泛兼容**：支持多种模型提供商的统一接口\n4. **清晰职责**：各层职责分明，便于维护和扩展\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [后端系统](#page-backends)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n \n\n# 核心概念\n\nOutlines 是一个保证 LLM 输出的结构化生成库。其核心理念是：在生成过程中直接约束输出格式，而不是在生成后通过解析、Regex 或脆弱的代码来修复不良输出。\n\n## 设计理念\n\n### 问题与解决方案\n\n传统的 LLM 输出处理方式存在以下问题：\n\n| 方法 | 问题 |\n|------|------|\n| 解析 (Parsing) | 输出可能不遵循预期格式 |\n| Regex 匹配 | 脆弱且难以维护 |\n| 后处理代码 | 容易在边界情况下失败 |\n\nOutlines 的解决方案是**在生成过程中直接保证结构有效性**，确保输出从一开始就是正确的格式。\n\n### Outlines 哲学\n\nOutlines 遵循一个简单的模式，模仿 Python 自身的类型系统。只需指定期望的输出类型，Outlines 就会确保数据完全匹配该结构：\n\n- 对于是/否响应，使用 `Literal[\"Yes\", \"No\"]`\n- 对于数值，使用 `int` 或 `float`\n- 对于复杂对象，使用 Pydantic 模型定义结构\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n A[用户代码] --> B[output_type]\n A --> C[prompt]\n end\n \n subgraph \"核心层\"\n B --> D[Generator]\n C --> D\n D --> E[Logits 处理器]\n end\n \n subgraph \"后端层\"\n E --> F[Transformers]\n E --> G[VLLM]\n E --> H[OpenAI]\n E --> I[Anthropic]\n E --> J[LlamaCpp]\n end\n \n subgraph \"模型层\"\n F --> K[本地模型]\n G --> L[vLLM Server]\n H --> M[OpenAI API]\n I --> N[Anthropic API]\n J --> O[本地 GGUF]\n end\n```\n\n资料来源：[outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## 输出类型系统\n\nOutlines 支持多种输出类型，用于约束生成内容的结构：\n\n### 基础类型\n\n| 类型 | 说明 | 示例 |\n|------|------|------|\n| `int` | 整数 | `model(\"What's 2+2?\", int)` |\n| `float` | 浮点数 | `model(\"Temperature?\", float)` |\n| `str` | 字符串 | `model(\"Name?\", str)` |\n\n### Literal 类型\n\n用于有限的选项集合：\n\n```python\nfrom typing import Literal\n\nresult = model(\"Sentiment?\", Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Pydantic 模型\n\n用于复杂结构化数据：\n\n```python\nfrom pydantic import BaseModel\n\nclass ProductReview(BaseModel):\n rating: int\n pros: list[str]\n cons: list[str]\n```\n\n### Regex 和 DSL\n\n```python\nfrom outlines.types import JsonSchema, Regex, integer\n\n# 使用 JSON Schema\nresult = model(\"Answer in JSON\", JsonSchema(schema))\n\n# 使用正则表达式\npattern = Regex(r\"^[\\d]{3}-[\\d]{4}$\")\nphone = model(\"Phone?\", pattern)\n```\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## 模型集成\n\nOutlines 支持多种模型后端，提供统一的调用接口：\n\n### 支持的模型类型\n\n| 模型类型 | 说明 | 文档链接 |\n|----------|------|----------|\n| `Transformers` | Hugging Face 本地模型 | 资料来源：[examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py) |\n| `OpenAI` | OpenAI API 模型 | - |\n| `Anthropic` | Anthropic Claude 模型 | - |\n| `VLLM` | vLLM 服务端 | - |\n| `LlamaCpp` | 本地 GGUF 格式模型 | - |\n| `Gemini` | Google Gemini 模型 | 资料来源：[outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py) |\n| `SGLang` | SGLang 服务端 | - |\n\n### 异步模型支持\n\n异步模型提供高性能的批量推理能力：\n\n```python\nfrom outlines import from_tgi\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(\n AsyncInferenceClient(\"http://localhost:11434\")\n)\n```\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Generator 类\n\nGenerator 是 Outlines v1 的核心组件，用于封装模型和输出类型的组合：\n\n### 特性\n\n- **可重用性**：一次编译，多次生成\n- **延迟编译**：输出类型的编译只在第一次生成时进行\n- **统一接口**：支持同步和异步调用\n\n### 使用方式\n\n```python\nfrom outlines import Generator, from_transformers\nfrom typing import Literal\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 直接调用\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n\n# 使用 Generator\ngenerator = Generator(model, Literal[\"pizza\", \"burger\"])\nresult = generator(\"What's your favorite food?\")\n```\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## 模型基类接口\n\nBaseModel 类提供了统一的模型调用接口：\n\n### 核心方法\n\n| 方法 | 说明 |\n|------|------|\n| `__call__` | 同步生成单个响应 |\n| `stream` | 流式生成响应 |\n| `batch` | 批量生成多个响应 |\n\n### 异步方法\n\n```python\nasync def stream(\n self,\n model_input: Any,\n output_type: Optional[Any] = None,\n backend: Optional[str] = None,\n **inference_kwargs: Any\n) -> AsyncIterator[Any]\n```\n\n```python\nasync def batch(\n self,\n model_input: List[Any],\n output_type: Optional[Any] = None,\n backend: Optional[str] = None,\n **inference_kwargs: Any\n) -> List[Any]\n```\n\n资料来源：[outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## 异常处理\n\nOutlines 提供了完整的异常层次结构：\n\n### 异常层次\n\n```\nOutlinesError\n├── APIError\n│ ├── AuthenticationError\n│ ├── PermissionDeniedError\n│ ├── NotFoundError\n│ ├── RateLimitError\n│ ├── BadRequestError\n│ ├── ServerError\n│ ├── APITimeoutError\n│ ├── APIConnectionError\n│ └── ProviderResponseError\n└── GenerationError\n```\n\n### APIError 特性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `provider` | `str \\| None` | 提供商名称（如 \"openai\"） |\n| `original_exception` | `Exception \\| None` | 原始 SDK 异常 |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 提供商请求 ID |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 人类可读的建议 |\n\n资料来源：[outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n## 应用场景\n\n### 函数调用\n\nOutlines 可以将自然语言转换为结构化函数调用：\n\n```python\ndef schedule_meeting(\n title: str,\n date: date,\n duration_minutes: int,\n attendees: List[str],\n location: Optional[str] = None\n):\n \"\"\"安排会议\"\"\"\n return f\"会议 '{title}' 已安排\"\n\nresult = model(\n \"I need to set up a meeting tomorrow at 2pm with Alice and Bob\",\n schedule_meeting\n)\n```\n\n### 模板系统\n\n使用 Jinja 模板生成动态提示：\n\n```python\ntemplate = outlines.Template.from_string(\"\"\"\n<|im_start|>user\n分析以下 {{ content_type }}的情感：\n\n{{ text }}\n<|im_end|>\n\"\"\")\n\nprompt = template(content_type=\"review\", text=\"Great product!\")\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### ReAct 模式\n\n实现 ReAct（Reasoning + Acting）模式：\n\n```python\ndef react_generator(prompt, stop=None, max_tokens=128):\n while True:\n response = llm(prompt, max_tokens=max_tokens)\n # 解析 action 和 action_input\n # 执行 action\n # 更新 prompt\n```\n\n资料来源：[examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py)\n\n## 快速开始\n\n### 1. 安装\n\n```shell\npip install outlines\n```\n\n### 2. 连接模型\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n```\n\n### 3. 结构化生成\n\n```python\nfrom typing import Literal\n\n# 分类\nsentiment = model(\"分析: '这个产品彻底改变了我的生活！'\", \n Literal[\"Positive\", \"Negative\", \"Neutral\"])\n\n# 提取数字\ntemperature = model(\"水的沸点是多少摄氏度？\", int)\n```\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n## 版本迁移说明\n\n### v0 到 v1 的主要变化\n\n| 旧版本 (v0) | 新版本 (v1) |\n|-------------|--------------|\n| `Function` 类 | `Application` 类 |\n| 关键字参数传模板变量 | 字典传模板变量 |\n| `load_lora()` 方法 | 直接传入 `LoRARequest` |\n| 模型需先创建生成器 | 模型可直接调用 |\n\n### 废弃的功能\n\n- `Exllamav2` 模型（接口不兼容）\n- `Function` 类（由 `Application` 替代）\n- 某些 `load_lora` 方法\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n---\n\n\n\n## 输出类型\n\n### 相关页面\n\n相关主题：[类型系统](#page-type-system), [生成器系统](#page-generator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/types/json_schema_utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/json_schema_utils.py)\n- [outlines/types/utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/utils.py)\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n \n\n# 输出类型\n\n## 概述\n\n输出类型（Output Types）是 Outlines 框架的核心概念之一，用于在 LLM 生成过程中约束输出结构，确保模型生成的文本符合预定义的格式规范。Outlines 将用户友好的 Python 类型（如 Pydantic 模型、Literal 类型、内置类型）转换为底层约束机制（正则表达式、FSM），在 token 级别控制生成过程。\n\n输出类型系统的设计遵循\"类型驱动 API\"原则：用户只需指定期望的输出类型，Outlines 自动处理约束编译和 token 掩码逻辑。\n\n## 核心类型体系\n\nOutlines 支持多种输出类型，按功能可分为以下几类：\n\n### 内置 Python 类型\n\n| 类型 | 说明 | 示例 |\n|------|------|------|\n| `int` | 整数类型 | `model(\"数字\", int)` → `42` |\n| `float` | 浮点数类型 | `model(\"温度\", float)` → `98.6` |\n| `str` | 字符串类型 | `model(\"名称\", str)` → `\"Alice\"` |\n\n### 字面量类型（Literal）\n\n用于生成预定义选项之一：\n\n```python\nfrom typing import Literal\n\nresult = model(\n \"分析情感：'产品很棒！'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\n```\n\n### Pydantic 模型\n\n复杂结构化输出的首选方式：\n\n```python\nfrom pydantic import BaseModel\n\nclass ProductReview(BaseModel):\n rating: int\n pros: list[str]\n cons: list[str]\n recommended: bool\n\nreview = model(\"分析评论...\", ProductReview)\n```\n\n### 正则表达式 DSL\n\n通过 `Regex`、`String`、`integer` 等 Term 类构建正则约束：\n\n```python\nfrom outlines.types import Regex, either, at_least\n\n# 简单正则\npattern = Regex(r\"[A-Z]{2}\\d{4}\")\n\n# 组合正则\ncomplex_pattern = either(\"yes\", \"no\", \"maybe\")\n```\n\n## 架构设计\n\n### 类型转换流程\n\n```mermaid\ngraph TD\n A[Python Type] --> B[Term Classes]\n B --> C[正则表达式]\n C --> D[FSM 编译]\n D --> E[Logits Processor]\n E --> F[Token Masking]\n F --> G[结构化生成]\n\n B --> B1[JsonSchema]\n B --> B2[CFG]\n B --> B3[Alternatives]\n B --> B4[KleeneStar]\n B --> B5[Literal Term]\n```\n\nOutlines 将输出类型处理分为三个逻辑阶段（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n1. **Term 类定义**：包含 JsonSchema、CFG 等独立使用的类型，以及组成正则 DSL 的 Alternatives、KleeneStar 等类\n2. **Python 类型到 Term 实例的转换**（`python_types_to_terms` 函数）\n3. **Term 实例到正则表达式的转换**（`to_regex` 函数）\n\n### Term 类层次\n\n```\nTerm (基类)\n├── JsonSchema # JSON Schema 约束\n├── CFG # 上下文无关文法\n├── LiteralTerm # 字面量值\n├── Regex # 正则表达式模式\n├── String # 字符串模式\n├── Integer # 整数模式\n├── Float # 浮点数模式\n├── Alternatives # 或运算 (|)\n├── Sequence # 序列连接\n├── KleeneStar # 零或多次 (*)\n├── Optional # 可选 (? 隐式)\n└── Group # 分组 (...)\n```\n\n## JSON Schema 支持\n\n### JsonSchema 类型\n\n可以直接使用 JSON Schema 字符串作为输出类型（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"2+2等于几？\", JsonSchema(json_schema))\n```\n\n### Schema 转换工具\n\n`json_schema_utils.py` 提供了 JSON Schema 与 Python 类型之间的双向转换：\n\n| 函数 | 功能 |\n|------|------|\n| `json_schema_dict_to_pydantic` | JSON Schema → Pydantic 模型 |\n| `json_schema_dict_to_typeddict` | JSON Schema → TypedDict |\n| `json_schema_dict_to_dataclass` | JSON Schema → Dataclass |\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_pydantic\n\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"age\": {\"type\": \"integer\"}\n }\n}\n\nPydanticModel = json_schema_dict_to_pydantic(schema)\n```\n\n## 正则表达式 DSL\n\n### Term 函数\n\nOutlines 提供了构建复杂正则模式的组合函数（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n| 函数 | 说明 | 示例 |\n|------|------|------|\n| `either(*items)` | 或运算 | `either(\"yes\", \"no\")` |\n| `optional(term)` | 可选 | `optional(\"maybe\")` |\n| `at_least(n, term)` | 至少 n 次 | `at_least(3, digit)` |\n| `integer()` | 整数模式 | 匹配 `-123`, `0`, `456` |\n| `float_number()` | 浮点数模式 | 匹配 `-1.5`, `3.14` |\n\n### 组合示例\n\n```python\nfrom outlines.types import either, optional, at_least, integer\n\n# 复杂模式：电话号码\nphone = either(\"+1\", \"+86\", \"\") + at_least(10, digit)\n\n# 组合多个 Term\nstatus = either(\"pending\", \"approved\", optional(\"rejected\"))\n```\n\n## 类型推断与验证\n\n### Python 类型检测\n\n`utils.py` 提供了类型检测工具函数（资料来源：[outlines/types/utils.py]()）：\n\n| 函数 | 功能 |\n|------|------|\n| `is_int(tp)` | 检测是否为整数类型 |\n| `is_int_instance(val)` | 检测值是否为整数 |\n| `is_float(tp)` | 检测是否为浮点类型 |\n| `is_str(tp)` | 检测是否为字符串类型 |\n| `get_schema_from_signature(fn)` | 从函数签名提取 schema |\n\n### Pydantic 集成\n\nOutlines 利用 Pydantic 的 `GetCoreSchemaHandler` 和 `GetJsonSchemaHandler` 实现类型适配（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n```python\nclass CustomType(BaseModel):\n value: str\n \n @classmethod\n def __get_pydantic_core_schema__(cls, source, handler):\n # 自定义 schema 处理逻辑\n return handler.generate_schema(cls)\n```\n\n## 与 Generator 的集成\n\n### Generator 类\n\nGenerator 是输出类型的消费者，它接收模型和输出类型，返回可复用的生成器实例（资料来源：[outlines/models/base.py:1-50]()）：\n\n```python\nfrom outlines import Generator, from_transformers\n\nmodel = from_transformers(...)\ngenerator = Generator(model, MyOutputType)\n\n# 复用编译结果\nresult1 = generator(\"prompt1\")\nresult2 = generator(\"prompt2\")\n```\n\n### Backend 选择\n\n不同输出类型可选择不同的 backend 实现（资料来源：[outlines/backends/__init__.py:1-50]()）：\n\n| Backend | 适用类型 | 特点 |\n|---------|----------|------|\n| `outlines_core` | Regex, JSON Schema | 通用实现 |\n| `xgrammar` | JSON Schema | 高性能 |\n| `llguidance` | Regex | 快速 FSM 编译 |\n\n```python\n# 指定 backend\nresult = model(\"prompt\", MySchema, backend=\"xgrammar\")\n```\n\n## 工作流程示例\n\n### 完整生成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Model as 模型实例\n participant Generator as Generator\n participant Backend as Backend\n participant FSM as FSM 编译器\n\n User->>Model: model(prompt, OutputType)\n Model->>Generator: 创建 Generator(model, OutputType)\n Generator->>Backend: get_logits_processor(OutputType)\n Backend->>FSM: 编译约束为 FSM\n FSM-->>Backend: FSM 状态机\n Backend-->>Generator: LogitsProcessor\n Generator-->>Model: 返回处理后的响应\n Model-->>User: 结构化输出结果\n```\n\n### 实际代码示例\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\nimport outlines\n\n# 定义输出结构\nclass AnalysisResult(BaseModel):\n sentiment: Literal[\"positive\", \"negative\", \"neutral\"]\n confidence: float\n keywords: list[str]\n\n# 使用模型生成\nmodel = outlines.from_transformers(...)\nresult = model(\"这个产品太棒了！\", AnalysisResult)\n\n# result 自动类型化为 AnalysisResult 实例\nprint(result.sentiment) # \"positive\"\n```\n\n## 最佳实践\n\n### 1. 优先使用 Pydantic 模型\n\n对于复杂结构，Pydantic 模型比原始 JSON Schema 更易维护：\n\n```python\n# 推荐\nclass Response(BaseModel):\n answer: str\n confidence: float\n\n# 而非\nschema = '{\"type\": \"object\", \"properties\": {\"answer\": {...}}}'\n```\n\n### 2. 善用 Literal 约束\n\n在分类任务中使用 Literal 限制输出范围：\n\n```python\nresult = model(prompt, Literal[\"A\", \"B\", \"C\", \"D\"])\n```\n\n### 3. 组合使用 DSL\n\n构建特定格式时使用正则 DSL：\n\n```python\nfrom outlines.types import Regex, either\n\ndate_pattern = Regex(r\"\\d{4}-\\d{2}-\\d{2}\")\n```\n\n## 总结\n\n输出类型系统是 Outlines 实现结构化生成的核心抽象层。它通过将 Python 类型系统与底层 FSM 约束机制解耦，为用户提供了简洁直观的 API。核心设计包括：\n\n- **类型驱动**：以 Python 类型作为主要约束规范\n- **多层转换**：类型 → Term → 正则 → FSM\n- **灵活组合**：支持嵌套、组合多种约束类型\n- **后端抽象**：允许针对不同场景选择最优实现\n\n开发者只需关注期望的输出结构，Outlines 自动处理底层约束编译和 token 掩码逻辑。\n\n---\n\n\n\n## 类型系统\n\n### 相关页面\n\n相关主题：[输出类型](#page-output-types), [核心概念](#page-core-concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/types/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/__init__.py)\n- [outlines/grammars/json.lark](https://github.com/dottxt-ai/outlines/blob/main/outlines/grammars/json.lark)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n \n\n# 类型系统\n\n## 概述\n\nOutlines 的类型系统是整个框架的核心基础设施，负责将 Python 类型声明转换为结构化生成的约束条件。该系统采用分层架构设计，从用户友好的 Python 类型逐步编译为底层的有限状态机（FSM），最终在 token 级别控制模型输出的有效性。\n\n类型系统的主要职责包括：\n\n- **类型到约束的转换**：将 Pydantic 模型、`Literal` 类型、`int`、`str` 等 Python 类型转换为正则表达式或 FSM\n- **术语（Term）DSL**：提供 `Regex`、`JsonSchema`、`CFG` 等术语类型，支持复杂输出规范的构建\n- **JSON Schema 处理**：支持 JSON Schema 格式的输出规范定义\n- **上下文无关文法（CFG）**：支持基于文法的结构化输出约束\n\n资料来源：[outlines/types/dsl.py:1-50]()\n\n## 核心架构\n\n### 类型系统分层设计\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 用户层 (User API) │\n│ Pydantic BaseModel / Literal / int / JsonSchema / CFG │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 术语层 (Term Layer) │\n│ Term 类: JsonSchema, CFG, Regex, String, ... │\n│ 组合函数: either, optional, at_least, ... │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 正则表达式层 (Regex Layer) │\n│ to_regex() → Python re.Pattern 对象 │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ FSM 编译层 (outlines-core) │\n│ build_regex_from_schema() → FSM │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Logits 处理层 │\n│ 处理器/guide.py: FSM 状态管理与 token 掩码 │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 类型转换流程\n\n```mermaid\ngraph LR\n A[Python 类型] --> B[Term 实例
python_types_to_terms]\n B --> C[正则表达式
to_regex]\n C --> D[FSM 有限状态机
outlines-core]\n D --> E[Token 掩码
Logits Processor]\n E --> F[结构化输出]\n \n A1[Pydantic Model] --> A\n A2[Literal Type] --> A\n A3[int / float] --> A\n A4[JsonSchema] --> B\n A5[CFG 文法] --> B\n```\n\n## 核心组件详解\n\n### 术语类（Term Classes）\n\n类型系统中的所有术语类都继承自统一接口，支持转换为正则表达式。核心术语类包括：\n\n| 术语类 | 用途 | 源码位置 |\n|--------|------|----------|\n| `JsonSchema` | 基于 JSON Schema 的输出约束 | [dsl.py:50-80]() |\n| `CFG` | 上下文无关文法约束 | [dsl.py:80-110]() |\n| `Regex` | 直接使用正则表达式模式 | [dsl.py:110-140]() |\n| `String` | 字符串字面量约束 | [dsl.py:140-170]() |\n| `Alternatives` | 多选一约束（对应正则 `\\|`） | [dsl.py:170-200]() |\n| `KleeneStar` | 零次或多次重复（对应 `*`） | [dsl.py:200-230]() |\n| `Optional` | 可选约束（对应 `?`） | [dsl.py:230-260]() |\n\n### DSL 组合函数\n\n类型系统提供了丰富的组合函数，用于构建复杂的输出规范：\n\n```python\nfrom outlines.types import either, optional, at_least, integer\n\n# either: 匹配多个选项之一\nchoice = either(\"option_a\", \"option_b\", \"option_c\")\n\n# optional: 可选的元素\nelement = optional(\"prefix:\")\n\n# at_least: 至少重复次数\nrepeated = at_least(integer(), min_times=1)\n\n# integer: 整数类型\nnum = integer()\n```\n\n资料来源：[outlines/types/dsl.py:200-280]()\n\n### Python 类型到 Term 的转换\n\n`python_types_to_terms()` 函数负责将标准 Python 类型转换为 Term 实例：\n\n| Python 类型 | 转换目标 | 示例 |\n|-------------|----------|------|\n| `int` | `integer()` | `int` → 整数约束 |\n| `float` | `float_()` | `float` → 浮点数约束 |\n| `str` | `string()` | `str` → 字符串约束 |\n| `bool` | `literal(True/False)` | `bool` → 布尔约束 |\n| `Literal[\"A\", \"B\"]` | `alternatives(...)` | 枚举值约束 |\n| `Enum` | `alternatives(...)` | 枚举类约束 |\n| `List[T]` | `array(term_from(T))` | 列表约束 |\n| `Dict[K, V]` | `object(...)` | 字典约束 |\n\n```python\ndef python_types_to_terms(py_type: Any) -> Term:\n \"\"\"将 Python 类型递归转换为 Term 实例\"\"\"\n # 处理 Literal 类型\n if is_literal(py_type):\n return alternatives(*get_args(py_type))\n \n # 处理枚举类型\n if is_enum(py_type):\n return alternatives(*[e.value for e in py_type])\n \n # 处理列表类型\n if is_list(py_type):\n element_type = get_args(py_type)[0]\n return array(python_types_to_terms(element_type))\n \n # ... 更多类型处理\n```\n\n资料来源：[outlines/types/dsl.py:300-400]()\n\n## 输出类型（Output Types）\n\n### 内置输出类型\n\nOutlines 支持多种输出类型，可直接作为模型调用的第二个参数：\n\n```python\nfrom typing import Literal\nfrom pydantic import BaseModel\n\n# 简单类型\nresult = model(\"What's 2+2?\", int) # 输出整数\n\n# 字面量类型\nsentiment = model(\"Great product!\", Literal[\"positive\", \"negative\", \"neutral\"])\n\n# Pydantic 模型\nclass User(BaseModel):\n name: str\n age: int\n email: str\n\nuser = model(\"Extract user info\", User)\n```\n\n### JsonSchema 类型\n\n`JsonSchema` 术语允许直接使用 JSON Schema 字符串定义输出结构：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '''\n{\n \"type\": \"object\",\n \"properties\": {\n \"answer\": {\"type\": \"number\"}\n }\n}\n'''\n\nresult = model(\"What's 2+2?\", JsonSchema(json_schema))\n```\n\n资料来源：[outlines/release_note.md:80-100]()\n\n### CFG（上下文无关文法）\n\nCFG 允许使用 Lark 语法定义自定义文法：\n\n```python\nfrom outlines.types import CFG\n\ngrammar = \"\"\"\nstart: expression\nexpression: term ((ADD | SUB) term)*\nterm: factor ((MUL | DIV) factor)*\nfactor: NUMBER | \"(\" expression \")\"\nADD: \"+\"\nSUB: \"-\"\nMUL: \"*\"\nDIV: \"/\"\nNUMBER: /[0-9]+/\n\"\"\"\n\nresult = model(\"Calculate 2+3*4\", CFG(grammar))\n```\n\n资料来源：[outlines/grammars/json.lark]() 及 [outlines/types/dsl.py]()\n\n## JSON Schema 与 Pydantic 互转\n\n类型系统提供了 JSON Schema 与其他格式的双向转换能力：\n\n### JSON Schema 转 Pydantic\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_pydantic\n\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"age\": {\"type\": \"integer\"}\n }\n}\n\nPydanticModel = json_schema_dict_to_pydantic(schema)\n```\n\n### JSON Schema 转 TypedDict\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_typeddict\n\nTypedDictModel = json_schema_dict_to_typeddict(schema)\n```\n\n### JSON Schema 转 Dataclass\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_dataclass\n\nDataClassModel = json_schema_dict_to_dataclass(schema)\n```\n\n资料来源：[outlines/types/dsl.py:60-90]()\n\n## 与生成器的集成\n\n### Generator 类\n\n`Generator` 类封装了模型和输出类型，提供了可复用的生成接口：\n\n```python\nfrom outlines import Generator, from_transformers\n\nmodel = from_transformers(...)\n\n# 创建生成器，输出类型编译一次\ngenerator = Generator(model, MyOutputType)\n\n# 多次复用同一生成器\nresult1 = generator(\"prompt1\")\nresult2 = generator(\"prompt2\")\n```\n\n### 模型直接调用\n\n模型也可以直接调用，类型系统在每次调用时编译：\n\n```python\n# 直接调用方式\nresult = model(\"prompt\", MyOutputType)\n\n# 等价于使用 Generator\ngenerator = Generator(model, MyOutputType)\nresult = generator(\"prompt\")\n```\n\n资料来源：[outlines/models/base.py:100-150]()\n\n## 异常处理\n\n类型系统在遇到无效类型或转换错误时，会抛出标准化的异常：\n\n| 异常类 | 描述 | 源码位置 |\n|--------|------|----------|\n| `OutlinesError` | 基础异常类 | [exceptions.py:30]() |\n| `APIError` | API 相关错误基类 | [exceptions.py:35]() |\n| `ProviderResponseError` | 提供商响应错误 | [exceptions.py:55]() |\n| `GenerationError` | 生成过程中的错误 | [exceptions.py:60]() |\n\n```python\ntry:\n result = model(\"prompt\", InvalidType)\nexcept OutlinesError as e:\n print(f\"类型系统错误: {e}\")\n```\n\n资料来源：[outlines/exceptions.py:20-70]()\n\n## 完整使用示例\n\n```python\nimport outlines\nfrom typing import Literal, List\nfrom pydantic import BaseModel\nfrom enum import Enum\n\n# 定义枚举类型\nclass Category(str, Enum):\n TECH = \"technology\"\n FOOD = \"food\"\n TRAVEL = \"travel\"\n\n# 定义 Pydantic 模型\nclass Article(BaseModel):\n title: str\n summary: str\n category: Category\n tags: List[str]\n published: bool\n\n# 初始化模型\nmodel = outlines.from_transformers(...)\n\n# 提取结构化信息\narticle = model(\n \"Write about AI advancements in healthcare\",\n Article\n)\n\n# 使用字面量类型快速分类\nsentiment = model(\n \"The new iPhone is amazing!\",\n Literal[\"positive\", \"negative\", \"neutral\"]\n)\n```\n\n## 模块导出\n\n`outlines.types` 模块的公共 API：\n\n```python\n# outlines/types/__init__.py 导出\n__all__ = [\n \"Term\", # 基础术语类\n \"JsonSchema\", # JSON Schema 术语\n \"CFG\", # 上下文无关文法\n \"Regex\", # 正则表达式术语\n \"String\", # 字符串术语\n \"integer\", # 整数术语工厂函数\n \"float_\", # 浮点数术语工厂函数\n \"string\", # 字符串术语工厂函数\n \"either\", # 组合函数：或\n \"optional\", # 组合函数：可选\n \"at_least\", # 组合函数：至少\n \"alternatives\", # 组合函数：多选一\n \"array\", # 组合函数：数组\n \"object\", # 组合函数：对象\n]\n```\n\n资料来源：[outlines/types/__init__.py]()\n\n---\n\n\n\n## 模型提供者\n\n### 相关页面\n\n相关主题：[生成器系统](#page-generator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/models/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/__init__.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/models/transformers.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/transformers.py)\n- [outlines/models/openai.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/openai.py)\n- [outlines/models/vllm.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/vllm.py)\n- [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n \n\n# 模型提供者\n\n## 概述\n\n模型提供者（Model Providers）是 Outlines 框架中负责与不同大语言模型后端进行交互的核心抽象层。Outlines 实现了统一的接口，使得用户可以使用相同的代码调用方式访问来自不同提供商的模型，包括本地 transformers 模型、OpenAI、Anthropic、vLLM 等。\n\nOutlines 的核心设计理念是\"**任何模型都适用**\"——相同的代码可以在不同的模型提供商之间切换而无需修改业务逻辑。这种设计通过模型提供者架构实现，将模型交互的细节封装在统一的接口之后。资料来源：[README.md:1-10]()\n\n## 架构设计\n\n### 分层架构\n\n```\n用户 API (outlines.models)\n ↓\n生成器类 (SteerableGenerator, BlackBoxGenerator)\n ↓\n类型系统 (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM 编译 (outlines-core: regex → FSM via interegular)\n ↓\nGuide 系统 (processors/guide.py: FSM 状态管理)\n ↓\nLogits 处理 (processors/structured.py: token 掩码)\n ↓\n模型提供者 (transformers, OpenAI, 等)\n```\n\n### 模型类层次结构\n\nOutlines 中的模型类分为两大类别：\n\n| 类别 | 描述 | 控制层级 | 支持的提供者 |\n|------|------|----------|--------------|\n| **SteerableModel** | 可操纵模型 | 完全控制 logits | transformers, llama.cpp, vLLM |\n| **BlackBoxModel** | 黑盒模型 | 通过 API 调用 | OpenAI, Anthropic, Google Gemini |\n\n资料来源：[llm.txt:1-25]()\n\n### 基类设计\n\n所有模型提供者都继承自 `BaseModel` 类，该类定义了共享的 `__call__`、`batch` 和 `stream` 方法。模型类必须定义 `type_adapter` 属性（类型为 `ModelTypeAdapter`），用于格式化输入和输出类型。\n\n```python\n# outlines/models/base.py\nclass BaseModel(ABC):\n \"\"\"所有异步模型的基类\"\"\"\n type_adapter: ModelTypeAdapter\n tensor_library_name: str\n\n async def __call__(\n self,\n model_input: Any,\n output_type: Optional[Any] = None,\n backend: Optional[str] = None,\n **inference_kwargs: Any\n ) -> Any:\n \"\"\"直接调用模型\"\"\"\n```\n\n资料来源：[outlines/models/base.py:1-50]()\n\n## 支持的模型提供者\n\n### 本地模型提供者\n\n#### Transformers\n\n`Transformers` 提供者允许使用 Hugging Face Transformers 库加载的本地模型。这是 Outlines 最基础的提供者，通过完全控制 logits 实现结构化生成。\n\n```python\nimport outlines\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"What's 2 + 2?\", int)\n```\n\n资料来源：[README.md:40-55]()\n\n#### vLLM\n\n`vLLM` 提供者支持通过 vLLM 推理引擎运行模型，提供高效的批量推理能力。\n\n```python\nfrom outlines import from_vllm\n\nmodel = from_vllm(\n \"microsoft/Phi-3-mini-4k-instruct\"\n)\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n```\n\n资料来源：[outlines/release_note.md:80-90]()\n\n#### Llama.cpp\n\n支持通过 llama.cpp 进行 CPU 或 GPU 推理的模型。\n\n### API 模型提供者\n\n#### OpenAI\n\n`OpenAI` 提供者封装了 OpenAI API，支持 GPT-4、GPT-3.5-Turbo 等模型。\n\n#### Anthropic\n\n支持 Claude 系列模型的调用。\n\n#### Google Gemini\n\n`Gemini` 提供者封装了 Google AI 的 Gemini 模型：\n\n```python\nfrom outlines import from_gemini\nfrom google.genai import Client\n\nmodel = from_gemini(Client(api_key=\"your-api-key\"))\n```\n\n资料来源：[outlines/models/gemini.py:1-30]()\n\n### 异步推理端点\n\nOutlines 还支持异步推理端点，特别适用于生产环境：\n\n| 提供者 | 类名 | 描述 |\n|--------|------|------|\n| SGLang | `AsyncSGLang` | 异步 SGLang 推理服务器 |\n| TGI | `AsyncTGI` | 异步 Text Generation Inference 服务器 |\n| vLLM | `AsyncVLLM` | 异步 vLLM 推理服务器 |\n\n```python\nfrom outlines import from_tgi\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n资料来源：[outlines/release_note.md:60-70]()\n\n## 核心接口\n\n### 模型调用方法\n\n所有模型提供者都实现了以下核心方法：\n\n#### `__call__` - 单次生成\n\n```python\nresult = model(\"Your prompt here\", output_type)\n```\n\n#### `stream` - 流式生成\n\n```python\nfor chunk in model.stream(\"Your prompt here\", output_type):\n print(chunk)\n```\n\n#### `batch` - 批量生成\n\n```python\nresults = model.batch(\n [\"prompt1\", \"prompt2\", \"prompt3\"],\n output_type\n)\n```\n\n资料来源：[outlines/models/base.py:50-120]()\n\n### 推理参数\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `model_input` | Any | 输入提示或提示列表 |\n| `output_type` | Optional[Any] | 输出类型约束 |\n| `backend` | Optional[str] | 后端名称（用于可操纵模型） |\n| `**inference_kwargs` | Any | 额外推理参数（如 max_tokens, temperature） |\n\n## 使用模式\n\n### 模式一：直接模型调用\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 直接调用\nresult = model(\"What's 2 + 2?\", int) # 返回 4\n```\n\n### 模式二：使用生成器\n\n生成器模式允许重用编译后的输出类型，提高批量调用效率：\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 创建生成器，输出类型只编译一次\ngenerator = Generator(model, int)\n\n# 多次使用同一生成器\nresult1 = generator(\"What's 2 + 2?\")\nresult2 = generator(\"What's 5 + 3?\")\n```\n\n资料来源：[outlines/release_note.md:90-105]()\n\n### 模式三：Pydantic 模型输出\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\nreview = model(\"生成一个产品评价\", ProductReview)\n```\n\n## LoRA 支持\n\n### vLLM LoRA 加载\n\nvLLM 模型支持通过 `lora_request` 参数加载 LoRA 适配器：\n\n```python\nfrom outlines import from_vllm\nfrom vllm import LLM\nfrom vllm.lora.request import LoRARequest\n\nmodel = from_vllm(LLM(\"microsoft/Phi-3-mini-4k-instruct\"))\nlora_request = LoRARequest(\"my_lora\", 1, \"path/to/lora/file\")\nresult = model(\"Write a short story\", str, lora_request=lora_request)\n```\n\n资料来源：[outlines/release_note.md:110-125]()\n\n## 版本变更说明\n\n### v1.0 主要变更\n\n在 Outlines v1.0 中，模型接口经历了重大修改：\n\n| 变更项 | 旧版本 | 新版本 |\n|--------|--------|--------|\n| 调用方式 | 先创建生成器再调用 | 直接 `model(prompt, output_type)` |\n| 流式接口 | 需创建特定生成器 | 所有模型都有 `stream` 方法 |\n| LoRA 加载 | `model.load_lora()` | 通过参数传递 `lora_request` |\n\n### 已弃用的提供者\n\n- **Exllamav2**: 由于接口不完全兼容，已从 Outlines 中移除\n\n资料来源：[outlines/release_note.md:30-50]()\n\n## 最佳实践\n\n### 1. 选择合适的提供者\n\n```mermaid\ngraph TD\n A[开始] --> B{需求场景}\n B -->|需要完全控制| C[SteerableModel]\n B -->|使用云端API| D[BlackBoxModel]\n C -->|HuggingFace模型| E[Transformers]\n C -->|高吞吐需求| F[vLLM]\n D -->|OpenAI生态| G[OpenAI]\n D -->|Anthropic生态| H[Anthropic]\n```\n\n### 2. 性能优化建议\n\n- **批量处理**：使用 `batch` 方法进行批量推理，减少 API 调用开销\n- **生成器复用**：频繁调用同一输出类型时使用 `Generator` 避免重复编译\n- **本地缓存**：transformers 模型首次加载后会被缓存\n\n### 3. 生产环境部署\n\n对于生产环境，推荐使用异步推理端点：\n\n```python\n# 推荐的生产配置\nasync_model = outlines.from_vllm(\n AsyncInferenceClient(\"http://your-vllm-server:8000\")\n)\n```\n\n## 相关模块\n\n- [Generator](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py) - 生成器核心类\n- [Type System](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py) - 类型系统与约束编译\n- [FSM Compilation](https://github.com/dottxt-ai/outlines/blob/main/outlines_core) - 有限状态机编译\n\n---\n\n\n\n## 生成器系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [模型提供者](#page-model-providers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\n- [outlines/inputs.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/inputs.py)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/__init__.py)\n \n\n# 生成器系统\n\n## 概述\n\n生成器系统（Generator System）是 Outlines 框架的核心抽象层，负责将结构化输出类型与语言模型解耦，实现可复用、可组合的生成管线。生成器接收模型实例和输出类型作为构造参数，返回一个可迭代的生成器对象，用户可反复使用该对象进行结构化文本生成而无需每次重新指定输出类型。\n\n生成器系统的核心价值在于**延迟编译和复用机制**：输出类型的有限状态机（FSM）仅在首次使用时编译一次，后续调用直接复用已编译的状态机，显著提升高频调用场景的性能。资料来源：[release_note.md]()\n\n## 架构设计\n\n### 层级结构\n\n```\n用户代码 (User Code)\n ↓\n┌─────────────────────────────────────┐\n│ Generator (生成器) │\n│ - 持有模型引用与输出类型 │\n│ - 管理 FSM 编译与缓存 │\n│ - 提供同步/异步生成接口 │\n└─────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────┐\n│ Model (模型适配器) │\n│ - SteerableModel / BlackBoxModel │\n│ - logits 处理 / API 调用封装 │\n└─────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────┐\n│ 输出类型系统 (Output Types) │\n│ - Pydantic → JsonSchema → Regex │\n│ - FSM 编译 (outlines-core) │\n└─────────────────────────────────────┘\n```\n\n### 关键设计决策\n\n| 决策 | 说明 |\n|------|------|\n| **惰性编译** | FSM 在首次调用时编译并持久化缓存 |\n| **统一接口** | 同步/异步、流式/批量使用相同 API |\n| **模型无关** | 支持本地模型(transformers)和 API 模型(OpenAI) |\n| **类型驱动** | Python 类型注解是主要的约束声明方式 |\n\n资料来源：[llm.txt]()\n\n## 核心组件\n\n### Generator 类\n\n`Generator` 是生成器系统的核心类，封装了模型实例、输出类型和编译后的 FSM。\n\n**构造函数签名：**\n\n```python\nGenerator(model, output_type, backend=None)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `Model` | 已初始化的 Outlines 模型实例 |\n| `output_type` | `type` | Python 类型或类型别名（int, Literal, BaseModel 等） |\n| `backend` | `str \\| None` | 后端名称，仅用于可转向模型(steerable models) |\n\n资料来源：[outlines/generator.py]()\n\n### 同步生成方法\n\n```python\n# 单次生成\nresult = generator(\"prompt\", **inference_kwargs)\n\n# 批量生成\nresults = generator.batch([\"prompt1\", \"prompt2\"], **inference_kwargs)\n```\n\n| 方法 | 参数 | 返回值 |\n|------|------|--------|\n| `__call__` | `prompt`, `**inference_kwargs` | `Any`（单条生成结果） |\n| `batch` | `List[prompt]`, `**inference_kwargs` | `List[Any]`（批量结果列表） |\n\n资料来源：[outlines/models/base.py:1-100]()\n\n### 异步生成方法\n\n```python\n# 异步单次生成\nresult = await generator(\"prompt\", **inference_kwargs)\n\n# 异步批量生成\nresults = await generator.batch([\"prompt1\", \"prompt2\"], **inference_kwargs)\n\n# 流式生成\nasync for chunk in generator.stream(\"prompt\", **inference_kwargs):\n print(chunk)\n```\n\n| 方法 | 参数 | 返回值 |\n|------|------|--------|\n| `__call__` (async) | `prompt`, `**inference_kwargs` | `Coroutine[Any]` |\n| `batch` (async) | `List[prompt]`, `**inference_kwargs` | `Coroutine[List[Any]]` |\n| `stream` (async) | `prompt`, `**inference_kwargs` | `AsyncIterator[Any]` |\n\n资料来源：[outlines/models/base.py:100-200]()\n\n## 输入处理系统\n\n`outlines/inputs.py` 负责处理各种格式的模型输入，将其标准化为统一的内部表示。\n\n### 输入类型支持\n\n| 输入类型 | 说明 | 示例 |\n|----------|------|------|\n| 字符串 | 纯文本 prompt | `\"今天天气如何？\"` |\n| 消息列表 | 对话格式 | `[{\"role\": \"user\", \"content\": \"...\"}]` |\n| 模板对象 | Jinja 模板渲染后的字符串 | `template(content=\"...\")` |\n\n资料来源：[outlines/inputs.py]()\n\n## 异常处理体系\n\nOutlines 定义了完整的异常层次结构，所有公共异常继承自 `OutlinesError` → `APIError` → `Exception`。\n\n### 异常类层次\n\n```\nOutlinesError\n└── APIError (provider: str, status_code: int, request_id: str)\n ├── AuthenticationError (401)\n ├── PermissionDeniedError (403)\n ├── NotFoundError (404)\n ├── BadRequestError (400)\n ├── RateLimitError (429)\n ├── ServerError (5xx)\n ├── APITimeoutError\n └── APIConnectionError\n└── ProviderResponseError\n└── GenerationError\n```\n\n### 异常属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `provider` | `str \\| None` | 提供商名称（如 `\"openai\"`） |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 请求追踪 ID |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 用户友好的建议信息 |\n\n资料来源：[outlines/exceptions.py]()\n\n## 使用模式\n\n### 模式一：直接模型调用 vs 生成器调用\n\n**直接调用模式（v1 新增）：**\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n```\n\n**生成器模式（可复用）：**\n\n```python\nfrom pydantic import BaseModel\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ngenerator = Generator(model, Character)\n# 多次调用无需重新指定输出类型\nresponse1 = generator(\"Create a male character.\")\nresponse2 = generator(\"Create a female character.\")\n```\n\n资料来源：[release_note.md]()\n\n### 模式二：流式生成\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ngenerator = Generator(model, str)\n\n# 同步流式（需调用 stream 方法）\nfor chunk in generator.stream(\"Write a story about a cat\"):\n print(chunk, end=\"\", flush=True)\n```\n\n### 模式三：异步批量处理\n\n```python\nimport asyncio\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nasync def main():\n model = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n )\n \n generator = Generator(model, str)\n prompts = [f\"Analyze sentiment: {text}\" for text in texts]\n results = await generator.batch(prompts)\n return results\n\nasyncio.run(main())\n```\n\n## API 模型生成器\n\n对于 API 类模型（如 OpenAI、Anthropic），生成器通过 `BlackBoxModel` 封装，利用提供商的结构化输出支持。\n\n### OpenAI 示例\n\n```python\nfrom openai import OpenAI\nfrom pydantic import BaseModel\nfrom outlines import Generator, from_openai\n\nclass Character(BaseModel):\n name: str\n age: int\n\nclient = OpenAI()\nmodel = from_openai(client)\ngenerator = Generator(model, Character)\n\nresult = generator(\"Create a character named Alice, age 25\")\n```\n\n资料来源：[release_note.md]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[创建 Generator] --> B{输出类型已编译?}\n B -->|否| C[调用 FSM 编译]\n C --> D[缓存 FSM]\n B -->|是| E[复用缓存 FSM]\n E --> F[准备 Prompt]\n D --> F\n F --> G{模型类型}\n G -->|Steerable| H[应用 Logits Processor]\n G -->|BlackBox| I[调用 API 结构化输出]\n H --> J[采样下一个 Token]\n I --> K[解析结构化响应]\n J --> L{是否结束?}\n L -->|否| J\n L -->|是| M[返回结果]\n K --> M\n```\n\n## 版本迁移指南\n\n### v0 到 v1 的变化\n\n| v0 方式 | v1 方式 |\n|---------|---------|\n| `generate.json(model, Character)` | `Generator(model, Character)` |\n| `models.openai(\"gpt-4o\")` | `from_openai(OpenAI())` |\n| `generator(prompt)` | `generator(prompt)` |\n| `model.load_lora(...)` | `lora_request=LoRARequest(...)` |\n\n资料来源：[release_note.md]()\n\n## 最佳实践\n\n1. **重复使用生成器**：创建生成器后应复用，避免重复编译 FSM\n2. **选择合适的输出类型**：简单类型用 `Literal`，复杂结构用 Pydantic\n3. **处理异常**：使用 `try/except OutlinesError` 捕获结构化错误\n4. **流式输出**：长文本生成使用流式接口改善用户体验\n5. **批量处理**：多 prompt 场景使用 `batch` 方法提高吞吐量\n\n## 相关模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| 生成器核心 | `outlines/generator.py` | Generator 类实现 |\n| 输入处理 | `outlines/inputs.py` | Prompt 标准化 |\n| 异常定义 | `outlines/exceptions.py` | 错误类型定义 |\n| 模型基类 | `outlines/models/base.py` | 模型抽象接口 |\n| 模型实现 | `outlines/models/*.py` | 各提供商适配器 |\n\n---\n\n\n\n## 后端系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/backends/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/base.py)\n- [outlines/backends/outlines_core.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/outlines_core.py)\n- [outlines/backends/xgrammar.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/xgrammar.py)\n- [outlines/backends/llguidance.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/llguidance.py)\n \n\n# 后端系统\n\n## 概述\n\nOutlines 的后端系统是负责将结构化输出约束（如正则表达式、JSON Schema、Pydantic 模型等）转换为模型推理过程中可执行的日志处理器（Logits Processor）的核心模块。该系统通过抽象化的后端接口，支持多种底层约束编译引擎，使用户能够在不同的生成场景中灵活选择最合适的约束实现方式。\n\n后端系统在整个 Outlines 架构中扮演着关键角色，它位于类型系统（Type System）与模型推理层之间，负责将高级约束描述编译为低级的有限状态机（FSM）或指导序列（Guide），并生成对应的日志处理器来控制 token 的生成过程。\n\n资料来源：[llm.txt]()\n\n## 架构设计\n\n### 层级架构\n\n```\n用户 API (outlines.models)\n ↓\n生成器类 (SteerableGenerator, BlackBoxGenerator)\n ↓\n类型系统 (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM 编译层 (outlines-core: regex → FSM via interegular)\n ↓\n后端系统 (backends/: 抽象接口与多种实现)\n ↓\n日志处理 (processors/structured.py: token masking)\n ↓\n模型提供者 (transformers, OpenAI, etc.)\n```\n\n### 后端抽象设计\n\nOutlines 采用后端抽象模式，为不同的约束编译引擎提供统一的接口。所有的后端实现都继承自基类 `Backend`，该基类定义了后端必须实现的核心方法，包括约束编译、状态管理和日志处理等。\n\n```mermaid\ngraph TD\n A[用户调用 Generator] --> B[Backend 抽象层]\n B --> C[OutlinesCore 后端]\n B --> D[XGrammar 后端]\n B --> E[LLGuidance 后端]\n C --> F[interegular 编译 FSM]\n D --> G[XGrammar 库]\n E --> H[llguidance 库]\n```\n\n资料来源：[outlines/backends/base.py]()\n\n## 核心组件\n\n### 后端基类 (Backend)\n\n所有具体后端实现都需要继承 `Backend` 基类，该类定义了统一的后端接口：\n\n| 方法名 | 功能描述 | 返回类型 |\n|--------|----------|----------|\n| `__init__` | 初始化后端实例 | None |\n| `name` | 返回后端标识名称 | str |\n| `__call__` | 执行约束编译 | Any |\n| `fsm_graph` | 获取 FSM 图结构 | FSMGraph |\n| `get一方文和_状态` | 获取当前 FSM 状态 | int |\n| `reset` | 重置 FSM 状态 | None |\n\n资料来源：[outlines/backends/base.py]()\n\n### OutlinesCore 后端\n\n`OutlinesCore` 是 Outlines 的默认后端实现，基于 `interegular` 库将正则表达式转换为有限状态机。该后端利用 `outlines-core` 包的底层能力，实现高效的 FSM 编译和状态管理。\n\n**核心特性：**\n- 使用 `interegular` 库进行正则表达式解析和 FSM 转换\n- 支持缓存已编译的 FSM 以提高性能\n- 兼容所有基于 FSM 的约束类型\n\n**工作流程：**\n```mermaid\ngraph LR\n A[正则表达式/约束] --> B[interegular 解析]\n B --> C[FSM 构建]\n C --> D[状态缓存]\n D --> E[Logits Processor]\n```\n\n资料来源：[outlines/backends/outlines_core.py]()\n\n### XGrammar 后端\n\n`XGrammar` 后端是由 MLC-LLM 社区开发的高性能约束编译引擎，专为结构化生成设计。该后端提供了比默认实现更快的约束匹配速度，特别适合对延迟敏感的应用场景。\n\n**主要优势：**\n- 高度优化的状态转移算法\n- 支持字节级（byte-level）约束\n- 更低的内存占用\n\n资料来源：[outlines/backends/xgrammar.py]()\n\n### LLGuidance 后端\n\n`LLGuidance` 后端提供了另一种结构化生成的实现方式，支持更复杂的约束语法和模式匹配能力。该后端适合需要高级约束特性的高级用户。\n\n**支持的功能：**\n- 复杂的正则表达式模式\n- 自定义终止条件\n- 多模态约束支持\n\n资料来源：[outlines/backends/llguidance.py]()\n\n## 后端注册与选择机制\n\n### 后端初始化\n\nOutlines 通过后端注册机制管理可用的后端实现。用户可以在创建生成器时指定使用哪个后端：\n\n```python\nfrom outlines import Generator, from_transformers\n\nmodel = from_transformers(\"microsoft/Phi-3-mini-4k-instruct\")\n\n# 使用默认后端\ngenerator = Generator(model, MySchema)\n\n# 指定特定后端\ngenerator = Generator(model, MySchema, backend=\"xgrammar\")\n```\n\n资料来源：[outlines/backends/__init__.py]()\n\n### 后端自动选择\n\n当用户未指定后端时，Outlines 会根据以下优先级自动选择可用的后端：\n\n1. **OutlinesCore**（默认）- 最广泛的兼容性\n2. **XGrammar** - 高性能场景\n3. **LLGuidance** - 高级约束需求\n\n## FSM 状态管理\n\n### 状态转换机制\n\nFSM（有限状态机）是约束编译的核心数据结构。每个 FSM 由多个状态节点和状态转移边组成，模型在生成每个 token 时都会根据当前状态确定合法的下一个 token 集合。\n\n```mermaid\ngraph TD\n S0[状态 0: 初始状态] -->|token A| S1[状态 1]\n S0 -->|token B| S2[状态 2]\n S1 -->|token C| S1\n S1 -->|token D| S3[状态 3: 终止]\n S2 -->|token E| S3\n S3 -->|\"[END]\"| S4[完成]\n```\n\n### 状态缓存\n\nOutlines 支持 FSM 缓存机制，避免对相同约束重复编译。缓存键由约束的哈希值和版本号组成，确保缓存的一致性和有效性。\n\n资料来源：[outlines/backends/outlines_core.py]()\n\n## 与生成器系统的集成\n\n### SteerableGenerator\n\n`SteerableGenerator` 是用于可控模型（如 Transformers、llama.cpp）的生成器类。它直接调用后端系统来创建日志处理器，在推理过程中实时过滤不合法的 token。\n\n```python\ngenerator = Generator(model, output_type, backend)\nresult = generator(\"提示词\")\n```\n\n### BlackBoxGenerator\n\n`BlackBoxGenerator` 用于黑盒 API 模型（如 OpenAI、Anthropic）。这类模型不支持直接的日志处理，因此后端系统会生成符合模型原生结构化输出格式的提示。\n\n资料来源：[outlines/models/base.py]()\n\n## 配置选项\n\n### 后端级配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `backend` | str | \"outlines_core\" | 指定使用的后端引擎 |\n| `cache_dir` | Path | None | FSM 缓存目录 |\n| `enable_cache` | bool | True | 是否启用 FSM 缓存 |\n| `fsm_options` | dict | {} | 后端特定配置项 |\n\n### 运行时配置\n\n在调用生成器时可以传递推理参数，这些参数会与后端的约束处理机制协同工作：\n\n```python\nresult = model(\n \"提示词\",\n temperature=0.7,\n max_tokens=100,\n num_beams=2\n)\n```\n\n## 扩展后端\n\n### 自定义后端接口\n\n要实现自定义后端，需要继承 `Backend` 基类并实现以下方法：\n\n1. `__init__(self, ...)`: 初始化后端\n2. `name(self) -> str`: 返回后端名称\n3. `__call__(self, ...) -> LogitsProcessor`: 创建日志处理器\n4. `fsm_graph(self) -> FSMGraph`: 返回 FSM 图结构\n\n### 注册自定义后端\n\n自定义后端可以通过修改 `backends/__init__.py` 来注册到 Outlines 系统中。\n\n资料来源：[outlines/backends/__init__.py]()\n\n## 性能考量\n\n### 后端性能对比\n\n| 后端 | 编译速度 | 推理速度 | 内存占用 | 兼容性 |\n|------|----------|----------|----------|--------|\n| OutlinesCore | 中等 | 中等 | 中等 | 高 |\n| XGrammar | 快 | 快 | 低 | 中 |\n| LLGuidance | 慢 | 快 | 高 | 中 |\n\n### 优化建议\n\n- **重复约束**：启用 FSM 缓存以避免重复编译\n- **高频调用**：考虑使用 XGrammar 后端以获得更低的延迟\n- **复杂约束**：使用 LLGuidance 后端的扩展语法支持\n\n## 错误处理\n\n### 后端相关异常\n\n后端系统可能抛出的异常类型包括：\n\n| 异常类型 | 触发场景 | 处理建议 |\n|----------|----------|----------|\n| `BackendNotAvailableError` | 请求的后端不可用 | 检查后端安装或使用备选后端 |\n| `CompilationError` | 约束编译失败 | 检查约束语法是否正确 |\n| `FSMCacheError` | 缓存读写失败 | 检查缓存目录权限 |\n\n资料来源：[outlines/exceptions.py]()\n\n## 相关文档\n\n- [核心特性文档](https://dottxt-ai.github.io/outlines/latest/features/core/generator)\n- [模型集成指南](https://dottxt-ai.github.io/outlines/latest/features/models)\n- [输出类型参考](https://dottxt-ai.github.io/outlines/latest/features/core/ouput_types)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：dottxt-ai/outlines\n\n摘要：发现 29 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] Streaming structured generation with partial validation。\n\n## 1. 安装坑 · 来源证据：[Feature] Streaming structured generation with partial validation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 维护坑 · 来源证据：Add more custom types\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：Add function calling and MCP support\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Feature Request] Add streaming support for structured generation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- 对用户的影响：Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 7. 安装坑 · 失败模式：installation: Outlines v1.2.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.6\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n\n## 8. 安装坑 · 失败模式：installation: Outlines v1.2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.8\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n\n## 9. 安装坑 · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 失败模式：migration: Outlines v1.2.10\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: Outlines v1.2.10\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.10\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10\n\n## 12. 维护坑 · 失败模式：migration: Outlines v1.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: Outlines v1.3.0\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.3.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0\n\n## 13. 维护坑 · 来源证据：Complex structure makes output empty\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：Incompatibility with vllm==0.19 because of some api changes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Incompatibility with vllm==0.19 because of some api changes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45101a3eaffb4eda98b4d597dd5aca64 | https://github.com/dottxt-ai/outlines/issues/1854 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_85cb7bc56eb64613b9ec65e51dea90e9 | https://github.com/dottxt-ai/outlines/issues/1847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 能力坑 · 失败模式：capability: Add function calling and MCP support\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Add function calling and MCP support\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Add function calling and MCP support\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add function calling and MCP support. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_dfb58c522eebbd15e72f7bfbfc936335 | https://github.com/dottxt-ai/outlines/issues/1626 | Add function calling and MCP support\n\n## 20. 能力坑 · 失败模式：capability: Add more custom types\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Add more custom types\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Add more custom types\n- 建议检查：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.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_8ba5f20b34d61b76171e5fdc02fffff8 | https://github.com/dottxt-ai/outlines/issues/1303 | Add more custom types\n\n## 21. 能力坑 · 失败模式：capability: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 对用户的影响：Developers may hit a documented source-backed failure mode: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 22. 能力坑 · 失败模式：capability: [Feature] Streaming structured generation with partial validation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: [Feature] Streaming structured generation with partial validation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature] Streaming structured generation with partial validation\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Streaming structured generation with partial validation. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0990edf56e70825cebd4d6337f2e9ec7 | https://github.com/dottxt-ai/outlines/issues/1856 | [Feature] Streaming structured generation with partial validation\n\n## 23. 能力坑 · 失败模式：capability: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_7477c33ba4e3aefcd5a822e817746461 | https://github.com/dottxt-ai/outlines/issues/1859 | 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n## 24. 能力坑 · 失败模式：conceptual: Complex structure makes output empty\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: Complex structure makes output empty\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Complex structure makes output empty\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_adb9b1e93b18abc454b9ec796b30af1a | https://github.com/dottxt-ai/outlines/issues/1861 | Complex structure makes output empty\n\n## 25. 运行坑 · 失败模式：performance: [Feature Request] Add streaming support for structured generation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this performance risk before relying on the project: [Feature Request] Add streaming support for structured generation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Add streaming support for structured generation\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f9e262951793c35ca4f0f973546df68f | https://github.com/dottxt-ai/outlines/issues/1842 | [Feature Request] Add streaming support for structured generation\n\n## 26. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | issue_or_pr_quality=unknown\n\n## 27. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | release_recency=unknown\n\n## 28. 维护坑 · 失败模式：maintenance: Outlines v1.2.12\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.12\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.12\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.12. Context: Observed when using docker\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_654aac443ea5eec7b12b4b1cbe602de9 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.13 | Outlines v1.2.12\n\n## 29. 维护坑 · 失败模式：maintenance: Outlines v1.2.9\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.9\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.9\n- 建议检查：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.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e26ccdb4b7c8d266e55856497effd5ae | https://github.com/dottxt-ai/outlines/releases/tag/1.2.9 | Outlines v1.2.9\n\n\n",
"markdown_key": "outlines",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:615403340",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/dottxt-ai/outlines"
},
{
"evidence_id": "art_3090310aeb7a4bd8a2e8814423c876e1",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/dottxt-ai/outlines#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "outlines 说明书",
"toc": [
"https://github.com/dottxt-ai/outlines 项目说明书",
"目录",
"Outlines 简介",
"项目概述",
"核心特性",
"快速开始指南",
"Generator 生成器",
"创建 Generator",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "6ae21356fd0dda00afd0ef0e76752904a22fc0aa",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/index.md",
"docs/core_concepts.md",
"docs/blog/index.md",
"docs/community/index.md",
"docs/community/versioning.md",
"docs/community/contribute.md",
"docs/community/examples.md",
"docs/community/feedback.md",
"docs/guide/architecture.md",
"docs/guide/fastapi_vllm_deployment.md",
"docs/guide/getting_started.md",
"docs/guide/vlm.md",
"docs/guide/installation.md",
"docs/guide/chat_templating.md",
"docs/guide/core_concepts.md",
"docs/guide/migration.md",
"docs/guide/selecting_an_inference_backend.md",
"docs/examples/deploy-using-modal.md",
"docs/examples/models_playing_chess.md",
"docs/examples/deploy-using-cerebrium.md",
"docs/examples/index.md",
"docs/examples/chain_of_thought.md",
"docs/examples/extract_event_details.md",
"docs/examples/chain_of_density.md",
"docs/examples/deploy-using-bentoml.md",
"docs/examples/qa-with-citations.md",
"docs/examples/receipt-digitization.md",
"docs/examples/extraction.md",
"docs/examples/structured_generation_workflow.md",
"docs/examples/classification.md",
"docs/examples/knowledge_graph_extraction.md",
"docs/examples/react_agent.md",
"docs/examples/earnings-reports.md",
"docs/examples/extract_event_details.py",
"docs/examples/read-pdfs.md",
"docs/examples/dating_profiles.md",
"docs/examples/simtom.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# outlines - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 outlines 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install outlines` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：249\n- 重要文件覆盖：40/249\n- 证据索引条目：80\n- 角色 / Skill 条目：68\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 outlines 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 outlines 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 outlines 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 68 个角色 / Skill / 项目文档条目。\n\n- **Gemini**（project_doc）：You need to install the google.genai libray to be able to use the Gemini API in Outlines. Install all optional dependencies of the Gemini model with: pip install \"outlines gemini \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/gemini.md`\n- **🚀 Building the future of structured generation**（project_doc）：Made with ❤👷️ by the team at .txt https://dottxt.co Trusted by NVIDIA, Cohere, HuggingFace, vLLM, etc. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Deploy Outlines on Beam**（project_doc）：1. Create an account here https://beam.cloud and install the Beam SDK 2. Download the app.py file to your computer 3. Deploy it as a serverless API by running: beam deploy app.py:predict 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/beam-cloud/README.md`\n- **Core concepts**（project_doc）：Coming soon. This will document various concepts at a high level, so users can understand Outlines before diving into specific implementations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/core_concepts.md`\n- **Index**（project_doc）：! assets/images/logo-light-mode.svg only-light { width=\"500\" } ! assets/images/logo-dark-mode.svg only-dark { width=\"500\" } 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **API Reference**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/index.md`\n- **Blog**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/index.md`\n- **What contributions?**（project_doc）：- Documentation contributions are very valuable to us! - Examples. Show us what you did with Outlines : - Bug reports with a minimum working examples in the issue tracker issues - Bug fixes are always a pleasure to review. - New features . Please start a new discussion discussions , or come chat with us discord beforehand! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/contribute.md`\n- **Community projects and articles**（project_doc）：Publishing examples and articles about Outlines are a meaningful way to contribute to the community. Here is a list of projects we are aware of. Drop us a line if we forgot yours! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/examples.md`\n- **Feedback**（project_doc）：If Outlines has been helpful to you, let us know on Discord discord or give us a shoutout on Twitter twitter ! It's always heartwarming ❤️ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/feedback.md`\n- **Community**（project_doc）：Outlines exists for a community of users who believe software doesn't need to be complicated. Who share the same passion for Large Language Models but don't want to compromise on robustness. Together, we are bringing these powerful models back to the world of software. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/index.md`\n- **Versioning Guide**（project_doc）：The Outlines project follows a structured versioning scheme designed to provide clarity and minimize risk for downstream dependents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/versioning.md`\n- **Summarize documents using Chain of Density prompting**（project_doc）：Summarize documents using Chain of Density prompting 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/chain_of_density.md`\n- **Chain of thought**（project_doc）：Chain of thought is a prompting technique introduced in the paper \"Chain-of-Thought Prompting Elicits Reasoning in Large Language Models\" https://arxiv.org/abs/2201.11903 where throught prompting the authors generate a series of intermediate reasoning steps which improves the ability of LLMs to perform complex reasoning. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/chain_of_thought.md`\n- **Classification**（project_doc）：Classification is a classic problem in NLP and finds many applications: spam detection, sentiment analysis, triaging of incoming requests, etc. We will use the example of a company that wants to sort support requests between those that require immediate attention URGENT , those that can wait a little STANDARD . You could easily extend the example by adding new labels. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/classification.md`\n- **Generate a synthetic dating profile from a description**（project_doc）：Generate a synthetic dating profile from a description 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/dating_profiles.md`\n- **Run Outlines using BentoML**（project_doc）：BentoML https://github.com/bentoml/BentoML is an open-source model serving library for building performant and scalable AI applications with Python. It comes with tools that you need for serving optimization, model packaging, and production deployment. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/deploy-using-bentoml.md`\n- **Run Outlines using Cerebrium**（project_doc）：Cerebrium https://www.cerebrium.ai/ is a serverless AI infrastructure platform that makes it easier for companies to build and deploy AI based applications. They offer Serverless GPU's with low cold start times with over 12 varieties of GPU chips that auto scale and you only pay for the compute you use. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/deploy-using-cerebrium.md`\n- **Run Outlines using Modal**（project_doc）：Modal https://modal.com/ is a serverless platform that allows you to easily run code on the cloud, including GPUs. It can come very handy for those of us who don't have a monster GPU at home and want to be able to quickly and easily provision, configure and orchestrate cloud infrastructure. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/deploy-using-modal.md`\n- **Extracting financial data from earnings reports**（project_doc）：Extracting financial data from earnings reports 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/earnings-reports.md`\n- **Extract Event Details**（project_doc）：This recipe demonstrates how to use the outlines library to extract structured event details from a text message. We will extract the title, location, and start date and time from messages like the following: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/extract_event_details.md`\n- **Named entity extraction**（project_doc）：Named Entity Extraction is a fundamental problem in NLP. It involves identifying and categorizing named entities within a document: people, organization, dates, places, etc. It is usually the first step in a more complex NLP worklow. Here we will use the example of a pizza restaurant that receives orders via their website and need to identify the number and types of pizzas that are being ordered. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/extraction.md`\n- **Examples**（project_doc）：This part of the documentation provides a few cookbooks that you can browse to get acquainted with the library and get some inspiration about what you could do with structured generation. Remember that you can easily change the model that is being used! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/index.md`\n- **Knowledge Graph Extraction**（project_doc）：In this guide, we use outlines https://dottxt-ai.github.io/outlines/ to extract a knowledge graph from unstructured text. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/knowledge_graph_extraction.md`\n- **Large language models playing chess**（project_doc）：Large language models playing chess 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/models_playing_chess.md`\n- **Generate Synthetic Data and Q&A with Citations**（project_doc）：Generate Synthetic Data and Q&A with Citations 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/qa-with-citations.md`\n- **ReAct Agent**（project_doc）：This example shows how to use outlines https://dottxt-ai.github.io/outlines/ to build your own agent with open weights local models and structured outputs. It is inspired by the blog post A simple Python implementation of the ReAct pattern for LLMs https://til.simonwillison.net/llms/python-react-pattern by Simon Willison https://simonwillison.net/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/react_agent.md`\n- **PDF to structured output with vision language models**（project_doc）：PDF to structured output with vision language models 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/read-pdfs.md`\n- **Receipt Data Extraction with VLMs**（project_doc）：You'll need to install the dependencies: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/receipt-digitization.md`\n- **Build perspective-taking agents with SimToM**（project_doc）：Build perspective-taking agents with SimToM 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/simtom.md`\n- **Structured Generation Workflow: Generating Synthetic Phone Numbers**（project_doc）：Structured Generation Workflow: Generating Synthetic Phone Numbers 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/structured_generation_workflow.md`\n- **Structured Generation Backends**（project_doc）：Outlines relies on a structured generation backend to control text generation for steerable models such thah they conform to the output type provided. One of those backends is of course outlines-core , but you also have access to two other libraries that fulfill the same purpose: llguidance and xgrammar . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/advanced/backends.md`\n- **Logits Processors**（project_doc）：Logits processors are objects that control text generation by modifying the probability distribution of possible next tokens. They do this by adjusting the logits raw model outputs at each generation step, effectively biasing the model's token selection. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/advanced/logits_processors.md`\n- **Error Handling**（project_doc）：For server-based models, Outlines provides a common exception hierarchy under OutlinesError . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/exceptions.md`\n- **Generator**（project_doc）：The Generator class is the core component of Outlines v1. Generator accepts a model ../models/index.md and an optional output type ../core/output types.md . If no output type is provided, the Generator will return unstructured text. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/generator.md`\n- **Model Inputs**（project_doc）：Outlines models accept various types of inputs to generate text. The input format depends on the capabilities of the underlying model and the type of task you want to perform. The most basic type of input is a single string prompt, it's accepted by all models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/inputs.md`\n- **Output Types**（project_doc）：Outlines provides a simple and intuitive way of defining the output structure of text generation. Possible output formats include basic Python types, multiple-choices, JSON schemas, regular expressions and context-free grammars. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/output_types.md`\n- **Features**（project_doc）：This section presents in details the different features of Outlines. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/index.md`\n- **Anthropic**（project_doc）：You need to install the anthropic library to be able to use the Anthropic API in Outlines. Install all optional dependencies of the Anthropic model with: pip install \"outlines anthropic \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/anthropic.md`\n- **Dottxt**（project_doc）：You need to install the dottxt python sdk to be able to use the Dottxt API in Outlines. Install all optional dependencies of the Dottxt model with: pip install \"outlines dottxt \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/dottxt.md`\n- **Models**（project_doc）：Outlines models are objects that wrap an inference client or engine. Models provide a standardized interface to generate structured text. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/index.md`\n- **llama.cpp**（project_doc）：Outlines provides an integration with Llama.cpp https://github.com/ggerganov/llama.cpp using the llama-cpp-python library https://github.com/abetlen/llama-cpp-python . Llamacpp allows to run quantized models on machines with limited compute. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/llamacpp.md`\n- **Mistral**（project_doc）：You need to install the mistralai library to be able to use the Mistral API in Outlines. Install all optional dependencies of the Mistral model with: pip install \"outlines mistral \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/mistral.md`\n- **mlx-lm**（project_doc）：Outlines provides an integration with mlx-lm https://github.com/ml-explore/mlx-examples/tree/main/llms , allowing models to be run quickly on Apple Silicon via the mlx https://ml-explore.github.io/mlx/build/html/index.html library. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/mlxlm.md`\n- **Ollama**（project_doc）：To be able to use Ollama in Outlines, you must install both Ollama and the optional dependency libraries of the model. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/ollama.md`\n- **OpenAI**（project_doc）：You need to install the openai library to be able to use the OpenAI API in Outlines. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/openai.md`\n- **OpenAI-Compatible APIs**（project_doc）：Many inference providers offer OpenAI-compatible APIs, allowing you to use the familiar OpenAI SDK while connecting to different backends. Outlines allows you can leverage various providers while maintaining consistent code. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/openai_compatible.md`\n- **Openrouter**（project_doc）：OpenRouter https://openrouter.ai/docs/api-reference/overview uses the same API as OpenAI, so both services are interoperable ./openai compatible.md using the openai library. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/openrouter.md`\n- **SGLang**（project_doc）：The Outlines SGLang model is intended to be used along with an SGLang instance running on a separate server can be local or remote . Make sure you have a SGLang server running and accessible before using the SGLang model. For instance by running: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/sglang.md`\n- **TGI**（project_doc）：The Outlines TGI model is intended to be used along with a HuggingFace Text Generation Inference server running locally or remotely . Make sure you have a TGI server running before using the TGI model. For instance running: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/tgi.md`\n- **Transformers**（project_doc）：You need to install the transformers library to be able to use the Transformers in Outlines. Install all optional dependencies of the Transformers model with: pip install \"outlines transformers \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/transformers.md`\n- **Transformers MultiModal**（project_doc）：The Outlines TransformersMultiModal model inherits from Transformers and shares most of its interface. Please start by reading the Transformers documentation ./transformers.md as this document only focuses on the specificities of TransformersMultiModal compared to Transformers . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/transformers_multimodal.md`\n- **vLLM**（project_doc）：The Outlines VLLM model is intended to be used along with a vLLM instance running on a separate server can be local or remote . Make sure you have a vLLM server running and accessible before using the VLLM model. For instance by running: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/vllm.md`\n- **vLLM Offline**（project_doc）：Outlines provides an integration with vLLM https://docs.vllm.ai/en/latest/ using the vllm library https://github.com/vllm-project/vllm . This model allows you to use vLLM in the \"Offline Inference\" mode, meaning that text generation happens within the model, there is no separate server. If you want to use vLLM with a server, see the VLLM model documentation ./vllm.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/vllm_offline.md`\n- **Application**（project_doc）：The Application class enables you to encapsulate a prompt template and an output type into a reusable component. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/utility/application.md`\n- **Regex DSL**（project_doc）：This library provides a Domain-Specific Language DSL to construct regular expressions in a more intuitive and modular way. It allows you to create complex regexes using simple building blocks that represent literal strings, patterns, and various quantifiers. Additionally, these custom regex types can be used directly as types in Pydantic https://pydantic-docs.helpmanual.io/ schemas to enforce pattern constraints dur… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/utility/regex_dsl.md`\n- **Template**（project_doc）：Outlines templates provide a way of creating reusable prompt structures with placeholders for dynamic content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/utility/template.md`\n- **Architecture Overview**（project_doc）：This guide explains how Outlines is organized so you can navigate the codebase, debug issues, and extend the library. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/architecture.md`\n- **Chat templating**（project_doc）：Instruction-tuned language models use \"special tokens\" to indicate different parts of text, such as the system prompt, the user prompt, any images, and the assistant's response. A chat template https://huggingface.co/docs/transformers/main/en/chat templating is how different types of input are composited together into a single, machine-readable string. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/chat_templating.md`\n- **Core concepts**（project_doc）：Coming soon. This will document various concepts at a high level, so users can understand Outlines before diving into specific implementations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/core_concepts.md`\n- **Deploying with FastAPI**（project_doc）：This guide demonstrates how to build a FastAPI application that leverages Outlines' async integration with vLLM. We create a customer support API that can intelligently categorize tickets and generate structured responses. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/fastapi_vllm_deployment.md`\n- **Getting Started**（project_doc）：We recommend using uv to install Outlines. You can find uv installation instructions here https://github.com/astral-sh/uv . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/getting_started.md`\n- **Installation**（project_doc）：We recommend using modern Python packaging tools such as uv for managing python dependencies. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/installation.md`\n- **Outlines 1.0 migration guide**（project_doc）：Outlines 1.0 introduces some breaking changes that affect the way you use the library. You are likely concerned by all of the following sections, so please read this document carefully until the end. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/migration.md`\n- **Models**（project_doc）：This guide should provide a general overview of the available models in the API reference /api/models/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/selecting_an_inference_backend.md`\n- **Vision-Language Models with Outlines**（project_doc）：Vision-Language Models with Outlines 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/vlm.md`\n- **Release Note**（project_doc）：The v1 intends on making Outlines more closely focused on constrained generation. To do so, we delegate a wider range of tasks to the users and inference libraries. On top of making Outlines leaner, this design provides more flexibility to the users and let them use interfaces they are already familiar with. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`outlines/release_note.md`\n- **🚧 Thank you for opening a PR!**（project_doc）：A few important guidelines and requirements before we can merge your PR: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Gemini**（documentation）：You need to install the google.genai libray to be able to use the Gemini API in Outlines. Install all optional dependencies of the Gemini model with: pip install \"outlines gemini \" . 证据：`docs/features/models/gemini.md`\n- **🚀 Building the future of structured generation**（documentation）：Made with ❤👷️ by the team at .txt https://dottxt.co Trusted by NVIDIA, Cohere, HuggingFace, vLLM, etc. 证据：`README.md`\n- **Deploy Outlines on Beam**（documentation）：1. Create an account here https://beam.cloud and install the Beam SDK 2. Download the app.py file to your computer 3. Deploy it as a serverless API by running: beam deploy app.py:predict 证据：`examples/beam-cloud/README.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Core concepts**（documentation）：Coming soon. This will document various concepts at a high level, so users can understand Outlines before diving into specific implementations. 证据：`docs/core_concepts.md`\n- **Index**（documentation）：! assets/images/logo-light-mode.svg only-light { width=\"500\" } ! assets/images/logo-dark-mode.svg only-dark { width=\"500\" } 证据：`docs/index.md`\n- **API Reference**（documentation）：API Reference 证据：`docs/api_reference/index.md`\n- **Blog**（documentation）：Blog 证据：`docs/blog/index.md`\n- **What contributions?**（documentation）：- Documentation contributions are very valuable to us! - Examples. Show us what you did with Outlines : - Bug reports with a minimum working examples in the issue tracker issues - Bug fixes are always a pleasure to review. - New features . Please start a new discussion discussions , or come chat with us discord beforehand! 证据：`docs/community/contribute.md`\n- **Community projects and articles**（documentation）：Publishing examples and articles about Outlines are a meaningful way to contribute to the community. Here is a list of projects we are aware of. Drop us a line if we forgot yours! 证据：`docs/community/examples.md`\n- **Feedback**（documentation）：If Outlines has been helpful to you, let us know on Discord discord or give us a shoutout on Twitter twitter ! It's always heartwarming ❤️ 证据：`docs/community/feedback.md`\n- **Community**（documentation）：Outlines exists for a community of users who believe software doesn't need to be complicated. Who share the same passion for Large Language Models but don't want to compromise on robustness. Together, we are bringing these powerful models back to the world of software. 证据：`docs/community/index.md`\n- **Versioning Guide**（documentation）：The Outlines project follows a structured versioning scheme designed to provide clarity and minimize risk for downstream dependents. 证据：`docs/community/versioning.md`\n- **Summarize documents using Chain of Density prompting**（documentation）：Summarize documents using Chain of Density prompting 证据：`docs/examples/chain_of_density.md`\n- **Chain of thought**（documentation）：Chain of thought is a prompting technique introduced in the paper \"Chain-of-Thought Prompting Elicits Reasoning in Large Language Models\" https://arxiv.org/abs/2201.11903 where throught prompting the authors generate a series of intermediate reasoning steps which improves the ability of LLMs to perform complex reasoning. 证据：`docs/examples/chain_of_thought.md`\n- **Classification**（documentation）：Classification is a classic problem in NLP and finds many applications: spam detection, sentiment analysis, triaging of incoming requests, etc. We will use the example of a company that wants to sort support requests between those that require immediate attention URGENT , those that can wait a little STANDARD . You could easily extend the example by adding new labels. 证据：`docs/examples/classification.md`\n- **Generate a synthetic dating profile from a description**（documentation）：Generate a synthetic dating profile from a description 证据：`docs/examples/dating_profiles.md`\n- **Run Outlines using BentoML**（documentation）：BentoML https://github.com/bentoml/BentoML is an open-source model serving library for building performant and scalable AI applications with Python. It comes with tools that you need for serving optimization, model packaging, and production deployment. 证据：`docs/examples/deploy-using-bentoml.md`\n- **Run Outlines using Cerebrium**（documentation）：Cerebrium https://www.cerebrium.ai/ is a serverless AI infrastructure platform that makes it easier for companies to build and deploy AI based applications. They offer Serverless GPU's with low cold start times with over 12 varieties of GPU chips that auto scale and you only pay for the compute you use. 证据：`docs/examples/deploy-using-cerebrium.md`\n- **Run Outlines using Modal**（documentation）：Modal https://modal.com/ is a serverless platform that allows you to easily run code on the cloud, including GPUs. It can come very handy for those of us who don't have a monster GPU at home and want to be able to quickly and easily provision, configure and orchestrate cloud infrastructure. 证据：`docs/examples/deploy-using-modal.md`\n- **Extracting financial data from earnings reports**（documentation）：Extracting financial data from earnings reports 证据：`docs/examples/earnings-reports.md`\n- **Extract Event Details**（documentation）：This recipe demonstrates how to use the outlines library to extract structured event details from a text message. We will extract the title, location, and start date and time from messages like the following: 证据：`docs/examples/extract_event_details.md`\n- **Named entity extraction**（documentation）：Named Entity Extraction is a fundamental problem in NLP. It involves identifying and categorizing named entities within a document: people, organization, dates, places, etc. It is usually the first step in a more complex NLP worklow. Here we will use the example of a pizza restaurant that receives orders via their website and need to identify the number and types of pizzas that are being ordered. 证据：`docs/examples/extraction.md`\n- **Examples**（documentation）：This part of the documentation provides a few cookbooks that you can browse to get acquainted with the library and get some inspiration about what you could do with structured generation. Remember that you can easily change the model that is being used! 证据：`docs/examples/index.md`\n- **Knowledge Graph Extraction**（documentation）：In this guide, we use outlines https://dottxt-ai.github.io/outlines/ to extract a knowledge graph from unstructured text. 证据：`docs/examples/knowledge_graph_extraction.md`\n- **Large language models playing chess**（documentation）：Large language models playing chess 证据：`docs/examples/models_playing_chess.md`\n- **Generate Synthetic Data and Q&A with Citations**（documentation）：Generate Synthetic Data and Q&A with Citations 证据：`docs/examples/qa-with-citations.md`\n- **ReAct Agent**（documentation）：This example shows how to use outlines https://dottxt-ai.github.io/outlines/ to build your own agent with open weights local models and structured outputs. It is inspired by the blog post A simple Python implementation of the ReAct pattern for LLMs https://til.simonwillison.net/llms/python-react-pattern by Simon Willison https://simonwillison.net/ . 证据：`docs/examples/react_agent.md`\n- **PDF to structured output with vision language models**（documentation）：PDF to structured output with vision language models 证据：`docs/examples/read-pdfs.md`\n- **Receipt Data Extraction with VLMs**（documentation）：You'll need to install the dependencies: 证据：`docs/examples/receipt-digitization.md`\n- **Build perspective-taking agents with SimToM**（documentation）：Build perspective-taking agents with SimToM 证据：`docs/examples/simtom.md`\n- **Structured Generation Workflow: Generating Synthetic Phone Numbers**（documentation）：Structured Generation Workflow: Generating Synthetic Phone Numbers 证据：`docs/examples/structured_generation_workflow.md`\n- **Structured Generation Backends**（documentation）：Outlines relies on a structured generation backend to control text generation for steerable models such thah they conform to the output type provided. One of those backends is of course outlines-core , but you also have access to two other libraries that fulfill the same purpose: llguidance and xgrammar . 证据：`docs/features/advanced/backends.md`\n- **Logits Processors**（documentation）：Logits processors are objects that control text generation by modifying the probability distribution of possible next tokens. They do this by adjusting the logits raw model outputs at each generation step, effectively biasing the model's token selection. 证据：`docs/features/advanced/logits_processors.md`\n- **Error Handling**（documentation）：For server-based models, Outlines provides a common exception hierarchy under OutlinesError . 证据：`docs/features/core/exceptions.md`\n- **Generator**（documentation）：The Generator class is the core component of Outlines v1. Generator accepts a model ../models/index.md and an optional output type ../core/output types.md . If no output type is provided, the Generator will return unstructured text. 证据：`docs/features/core/generator.md`\n- **Model Inputs**（documentation）：Outlines models accept various types of inputs to generate text. The input format depends on the capabilities of the underlying model and the type of task you want to perform. The most basic type of input is a single string prompt, it's accepted by all models. 证据：`docs/features/core/inputs.md`\n- **Output Types**（documentation）：Outlines provides a simple and intuitive way of defining the output structure of text generation. Possible output formats include basic Python types, multiple-choices, JSON schemas, regular expressions and context-free grammars. 证据：`docs/features/core/output_types.md`\n- **Features**（documentation）：This section presents in details the different features of Outlines. 证据：`docs/features/index.md`\n- **Anthropic**（documentation）：You need to install the anthropic library to be able to use the Anthropic API in Outlines. Install all optional dependencies of the Anthropic model with: pip install \"outlines anthropic \" . 证据：`docs/features/models/anthropic.md`\n- **Dottxt**（documentation）：You need to install the dottxt python sdk to be able to use the Dottxt API in Outlines. Install all optional dependencies of the Dottxt model with: pip install \"outlines dottxt \" . 证据：`docs/features/models/dottxt.md`\n- **Models**（documentation）：Outlines models are objects that wrap an inference client or engine. Models provide a standardized interface to generate structured text. 证据：`docs/features/models/index.md`\n- **llama.cpp**（documentation）：Outlines provides an integration with Llama.cpp https://github.com/ggerganov/llama.cpp using the llama-cpp-python library https://github.com/abetlen/llama-cpp-python . Llamacpp allows to run quantized models on machines with limited compute. 证据：`docs/features/models/llamacpp.md`\n- **Mistral**（documentation）：You need to install the mistralai library to be able to use the Mistral API in Outlines. Install all optional dependencies of the Mistral model with: pip install \"outlines mistral \" . 证据：`docs/features/models/mistral.md`\n- **mlx-lm**（documentation）：Outlines provides an integration with mlx-lm https://github.com/ml-explore/mlx-examples/tree/main/llms , allowing models to be run quickly on Apple Silicon via the mlx https://ml-explore.github.io/mlx/build/html/index.html library. 证据：`docs/features/models/mlxlm.md`\n- **Ollama**（documentation）：To be able to use Ollama in Outlines, you must install both Ollama and the optional dependency libraries of the model. 证据：`docs/features/models/ollama.md`\n- **OpenAI**（documentation）：You need to install the openai library to be able to use the OpenAI API in Outlines. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 证据：`docs/features/models/openai.md`\n- **OpenAI-Compatible APIs**（documentation）：Many inference providers offer OpenAI-compatible APIs, allowing you to use the familiar OpenAI SDK while connecting to different backends. Outlines allows you can leverage various providers while maintaining consistent code. 证据：`docs/features/models/openai_compatible.md`\n- **Openrouter**（documentation）：OpenRouter https://openrouter.ai/docs/api-reference/overview uses the same API as OpenAI, so both services are interoperable ./openai compatible.md using the openai library. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 证据：`docs/features/models/openrouter.md`\n- **SGLang**（documentation）：The Outlines SGLang model is intended to be used along with an SGLang instance running on a separate server can be local or remote . Make sure you have a SGLang server running and accessible before using the SGLang model. For instance by running: 证据：`docs/features/models/sglang.md`\n- **TGI**（documentation）：The Outlines TGI model is intended to be used along with a HuggingFace Text Generation Inference server running locally or remotely . Make sure you have a TGI server running before using the TGI model. For instance running: 证据：`docs/features/models/tgi.md`\n- **Transformers**（documentation）：You need to install the transformers library to be able to use the Transformers in Outlines. Install all optional dependencies of the Transformers model with: pip install \"outlines transformers \" . 证据：`docs/features/models/transformers.md`\n- **Transformers MultiModal**（documentation）：The Outlines TransformersMultiModal model inherits from Transformers and shares most of its interface. Please start by reading the Transformers documentation ./transformers.md as this document only focuses on the specificities of TransformersMultiModal compared to Transformers . 证据：`docs/features/models/transformers_multimodal.md`\n- **vLLM**（documentation）：The Outlines VLLM model is intended to be used along with a vLLM instance running on a separate server can be local or remote . Make sure you have a vLLM server running and accessible before using the VLLM model. For instance by running: 证据：`docs/features/models/vllm.md`\n- **vLLM Offline**（documentation）：Outlines provides an integration with vLLM https://docs.vllm.ai/en/latest/ using the vllm library https://github.com/vllm-project/vllm . This model allows you to use vLLM in the \"Offline Inference\" mode, meaning that text generation happens within the model, there is no separate server. If you want to use vLLM with a server, see the VLLM model documentation ./vllm.md . 证据：`docs/features/models/vllm_offline.md`\n- **Application**（documentation）：The Application class enables you to encapsulate a prompt template and an output type into a reusable component. 证据：`docs/features/utility/application.md`\n- **Regex DSL**（documentation）：This library provides a Domain-Specific Language DSL to construct regular expressions in a more intuitive and modular way. It allows you to create complex regexes using simple building blocks that represent literal strings, patterns, and various quantifiers. Additionally, these custom regex types can be used directly as types in Pydantic https://pydantic-docs.helpmanual.io/ schemas to enforce pattern constraints during text generation. 证据：`docs/features/utility/regex_dsl.md`\n- **Template**（documentation）：Outlines templates provide a way of creating reusable prompt structures with placeholders for dynamic content. 证据：`docs/features/utility/template.md`\n- **Architecture Overview**（documentation）：This guide explains how Outlines is organized so you can navigate the codebase, debug issues, and extend the library. 证据：`docs/guide/architecture.md`\n- **Chat templating**（documentation）：Instruction-tuned language models use \"special tokens\" to indicate different parts of text, such as the system prompt, the user prompt, any images, and the assistant's response. A chat template https://huggingface.co/docs/transformers/main/en/chat templating is how different types of input are composited together into a single, machine-readable string. 证据：`docs/guide/chat_templating.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/features/models/gemini.md`, `README.md`, `examples/beam-cloud/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/features/models/gemini.md`, `README.md`, `examples/beam-cloud/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Outlines 简介**：importance `high`\n - source_paths: README.md, outlines/release_note.md\n- **安装指南**：importance `high`\n - source_paths: pyproject.toml, environment.yml\n- **快速开始**：importance `high`\n - source_paths: README.md, examples/dating_profile.py, examples/react.py\n- **系统架构**：importance `high`\n - source_paths: outlines/generator.py, outlines/backends/__init__.py, outlines/processors/__init__.py, llm.txt\n- **核心概念**：importance `high`\n - source_paths: llm.txt, outlines/backends/base.py\n- **输出类型**：importance `high`\n - source_paths: outlines/types/dsl.py, outlines/types/json_schema_utils.py, outlines/types/utils.py\n- **类型系统**：importance `medium`\n - source_paths: outlines/types/dsl.py, outlines/types/__init__.py, outlines/grammars/json.lark\n- **模型提供者**：importance `high`\n - source_paths: outlines/models/__init__.py, outlines/models/base.py, outlines/models/transformers.py, outlines/models/openai.py, outlines/models/vllm.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `6ae21356fd0dda00afd0ef0e76752904a22fc0aa`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/index.md`, `docs/core_concepts.md`, `docs/blog/index.md`, `docs/community/index.md`, `docs/community/versioning.md`, `docs/community/contribute.md`, `docs/community/examples.md`, `docs/community/feedback.md`, `docs/guide/architecture.md`, `docs/guide/fastapi_vllm_deployment.md`, `docs/guide/getting_started.md`, `docs/guide/vlm.md`, `docs/guide/installation.md`, `docs/guide/chat_templating.md`, `docs/guide/core_concepts.md`, `docs/guide/migration.md`, `docs/guide/selecting_an_inference_backend.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Feature] Streaming structured generation with partial validation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Add more custom types\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Add function calling and MCP support\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Feature Request] Add streaming support for structured generation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- Trigger: Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- Host AI rule: 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\n- Why it matters: Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- Evidence: 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\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 失败模式：installation: Outlines v1.2.6\n\n- Trigger: Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- Why it matters: Upgrade or migration may change expected behavior: Outlines v1.2.6\n- Evidence: failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 失败模式：installation: Outlines v1.2.8\n\n- Trigger: Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- Why it matters: Upgrade or migration may change expected behavior: Outlines v1.2.8\n- Evidence: failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：dottxt-ai/outlines\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Feature] Streaming structured generation with partial validation（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Add more custom types（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Add function calling and MCP support（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Feature Request] Add streaming support for structured generation（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/dottxt-ai/outlines 项目说明书\n\n生成时间: 2026-05-21 17:17:18 UTC\n\n## 目录\n\n- [Outlines 简介](#page-introduction)\n- [安装指南](#page-installation)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [核心概念](#page-core-concepts)\n- [输出类型](#page-output-types)\n- [类型系统](#page-type-system)\n- [模型提供者](#page-model-providers)\n- [生成器系统](#page-generator)\n- [后端系统](#page-backends)\n\n\n\n## Outlines 简介\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n \n\n# Outlines 简介\n\n## 项目概述\n\nOutlines 是一个用于引导大语言模型（LLM）生成结构化输出的开源框架。该项目由 .txt 团队开发和维护，旨在解决 LLM 输出不确定性这一核心问题。\n\n传统的 LLM 应用通常在生成后通过解析、正则表达式或脆弱的解析代码来尝试修复不良输出，这种方式容易出错且难以维护。Outlines 采用不同的方法：在生成过程中直接确保输出结构符合预期，从而从根本上保证输出的有效性。\n\n**核心价值主张：**\n\n- **结构保证**：在生成过程中直接约束输出格式，而非事后解析\n- **模型无关性**：同一套代码可在 OpenAI、Ollama、vLLM 等多种模型上运行\n- **类型安全**：通过 Python 类型系统直接指定输出类型\n- **提供商独立性**：切换模型时无需修改业务代码\n\n资料来源：[README.md:1-30]()\n\n## 核心特性\n\n### 支持的模型提供商\n\nOutlines 支持多种模型集成方式，形成统一的抽象接口：\n\n| 提供商类型 | 具体实现 | 异步支持 |\n|-----------|---------|---------|\n| 本地模型 | Transformers、VLLM、LlamaCpp、Ollama | 是 |\n| OpenAI 系列 | OpenAI、Azure OpenAI | 是 |\n| Anthropic 系列 | Claude 模型 | 是 |\n| Google 系列 | Gemini | 是 |\n| 其他 | SGLang、TGI、Transformers.js | 是 |\n\n异步模型包括 `AsyncSGLang`、`AsyncTGI`、`AsyncVLLM` 等，可通过以下方式初始化：\n\n```python\nimport outlines\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n资料来源：[README.md:60-80]()\n\n### 输出类型系统\n\nOutlines 的核心设计理念是让用户通过 Python 类型系统直接指定期望的输出结构：\n\n| 输出类型 | 定义方式 | 示例 |\n|---------|---------|-----|\n| 字面量类型 | `Literal` | `Literal[\"Yes\", \"No\"]` |\n| 数值类型 | Python 内置类型 | `int`、`float` |\n| 列表类型 | `list[T]` | `list[str]` |\n| 复杂对象 | Pydantic 模型 | `BaseModel` 子类 |\n| 正则约束 | Regex DSL | `Regex`、`String` |\n| JSON Schema | `JsonSchema` | `JsonSchema(schema_str)` |\n| 上下文无关文法 | `CFG` | CFG 语法定义 |\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass ProductReview(BaseModel):\n rating: Literal[\"poor\", \"fair\", \"good\", \"excellent\"]\n pros: list[str]\n cons: list[str]\n summary: str\n```\n\n资料来源：[outlines/release_note.md:30-60]()\n\n### 架构设计\n\nOutlines 采用分层架构设计，核心组件关系如下：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[模型调用层]\n B --> C[Generator 生成器]\n C --> D[输出类型编译]\n D --> E[Logits Processor]\n E --> F[底层模型推理]\n \n G[Transformers] --> F\n H[VLLM] --> F\n I[OpenAI] --> F\n J[Anthropic] --> F\n \n K[BaseModel] --> D\n L[Literal Type] --> D\n M[Regex DSL] --> D\n```\n\n#### 模型基类设计\n\n所有模型类继承自 `BaseModel`（异步）或 `BaseModel` 的变体，提供统一的调用接口：\n\n```mermaid\ngraph LR\n A[__call__] --> B[创建 Generator]\n C[batch] --> B\n D[stream] --> B\n B --> E[执行生成]\n \n F[type_adapter] -.-> A\n G[tensor_library_name] -.-> F\n```\n\n模型类必须定义 `type_adapter` 属性（类型 `ModelTypeAdapter`）和 `tensor_library_name` 属性。\n\n资料来源：[outlines/models/base.py:1-50]()\n\n## 快速开始指南\n\n### 安装\n\n```shell\npip install outlines\n```\n\n资料来源：[README.md:35-40]()\n\n### 基本使用流程\n\n```mermaid\ngraph LR\n A[安装 Outlines] --> B[加载模型]\n B --> C[定义输出类型]\n C --> D[调用模型生成]\n D --> E[获取结构化输出]\n```\n\n### 第一步：连接模型\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n资料来源：[README.md:42-55]()\n\n### 第二步：简单分类任务\n\n```python\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n```\n\n资料来源：[README.md:56-65]()\n\n### 第三步：数值提取\n\n```python\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n```\n\n资料来源：[README.md:66-70]()\n\n### 第四步：复杂结构\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n\nreview = model(\n \"Write a review for the iPhone 15 Pro\",\n ProductReview\n)\n```\n\n资料来源：[README.md:71-90]()\n\n## Generator 生成器\n\nGenerator 是 Outlines v1 版本引入的核心组件，用于封装模型和输出类型的组合。\n\n### 设计目的\n\nGenerator 的主要价值在于**可重用性**和**编译缓存**：\n\n| 特性 | 说明 |\n|-----|------|\n| 可重用性 | 无需每次调用时指定输出类型 |\n| 编译缓存 | 输出类型的编译（当适用时）仅执行一次 |\n| 批处理支持 | 同一 Generator 可处理多个输入 |\n\n### 基本用法\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n age: int\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 创建 Generator\ngenerator = Generator(model, Character)\n\n# 多次调用，输出类型无需重复指定\nresult1 = generator(\"Create a young wizard character\")\nresult2 = generator(\"Create an old warrior character\")\n```\n\n### Generator 方法\n\n| 方法 | 描述 | 异步版本 |\n|-----|------|---------|\n| `__call__` | 单次生成 | `async def __call__` |\n| `batch` | 批量生成 | `async def batch` |\n| `stream` | 流式生成 | `async def stream` |\n\n资料来源：[outlines/models/base.py:50-120]()\n\n## 正则表达式 DSL\n\nOutlines 提供了正则表达式领域特定语言（Regex DSL），允许通过代码组合构建复杂的正则模式。\n\n### 可用组件\n\n| 组件 | 功能 | 示例 |\n|-----|------|-----|\n| `Regex` | 匹配正则表达式 | `Regex(r\"[0-9]+\")` |\n| `String` | 匹配字符串字面量 | `String(\"yes\")` |\n| `either` | 或运算 | `either(a, b)` |\n| `optional` | 可选修饰 | `optional(pattern)` |\n| `at_least` | 至少重复次数 | `at_least(n, pattern)` |\n| `integer` | 匹配整数 | `integer()` |\n\n### 使用示例\n\n```python\nfrom outlines.types import at_least, either, integer, optional\n\n# 构建复杂模式\npattern = either(\n integer(),\n at_least(2, String(\"ab\"))\n)\n```\n\n### JsonSchema 类型\n\n`JsonSchema` 是一个独立的 Term，可直接用作输出类型：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2? Respond in a json\", JsonSchema(json_schema))\n```\n\n资料来源：[outlines/release_note.md:60-90]()\n\n## 异常处理体系\n\nOutlines 定义了完整的异常层次结构，便于应用程序进行错误处理。\n\n### 异常层次\n\n```mermaid\ngraph TD\n A[Exception] --> B[OutlinesError]\n B --> C[APIError]\n C --> D[AuthenticationError]\n C --> E[PermissionDeniedError]\n C --> F[NotFoundError]\n C --> G[RateLimitError]\n C --> H[BadRequestError]\n C --> I[ServerError]\n C --> J[APITimeoutError]\n C --> K[APIConnectionError]\n B --> L[ProviderResponseError]\n B --> M[GenerationError]\n```\n\n### APIError 核心属性\n\n| 属性 | 类型 | 说明 |\n|-----|------|------|\n| `provider` | `str \\| None` | 提供商名称，如 `\"openai\"` |\n| `original_exception` | `Exception \\| None` | 原始 SDK 异常 |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 提供商请求 ID |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 人类可读的建议信息 |\n\n### 错误处理示例\n\n```python\nfrom outlines.exceptions import APIError, RateLimitError, normalize_provider_errors\n\ntry:\n with normalize_provider_errors(provider=\"openai\"):\n result = model(\"Generate something\", str)\nexcept RateLimitError as e:\n print(f\"Rate limited: {e.hint}\")\nexcept APIError as e:\n print(f\"API Error: {e.request_id}\")\n```\n\n资料来源：[outlines/exceptions.py:1-60]()\n\n## 版本迁移指南\n\n### v0 到 v1 重要变更\n\n#### 移除的功能\n\n| 旧功能 | 替代方案 | 说明 |\n|-------|---------|------|\n| `Function` 类 | `Application` 类 | Application 不在初始化时绑定模型 |\n| `Template.from_file` | `Template.from_string` + 文件读取 | 简化模板加载逻辑 |\n| Exllamav2 模型 | 无替代 | 接口不兼容，已移除 |\n| `load_lora` 方法 | LoRA 请求参数 | 通过 `lora_request` 参数传递 |\n\n#### Function 到 Application 迁移\n\n```python\n# v0 写法（已废弃）\nfrom outlines import Function, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\nfn = Function(template, Character, \"hf-internal-testing/tiny-random-GPTJForCausalLM\")\nresponse = fn(gender=\"female\")\n\n# v1 写法（推荐）\nfrom outlines import Application, Template\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\nresponse = app(model, {\"gender\": \"female\"})\n```\n\n#### LoRA 加载变更\n\n```python\n# v0 写法（已废弃）\nmodel.load_lora(\"path/to/lora/file\")\n\n# v1 写法（推荐）\nfrom vllm.lora.request import LoRARequest\n\nlora_request = LoRARequest(\"my_lora\", 1, \"path/to/lora/file\")\nresponse = model(\"Write a short story\", str, lora_request=lora_request)\n```\n\n资料来源：[outlines/release_note.md:1-40]()\n\n### 模型调用方式变化\n\nv1 版本支持直接调用模型，无需先创建生成器：\n\n```python\n# 方式一：直接调用（v1 新增）\nresult = model(\"Write a story\", str, max_tokens=100)\n\n# 方式二：使用 Generator（v1 新增）\ngenerator = Generator(model, str)\nresult = generator(\"Write a story\", max_tokens=100)\n```\n\n两种方式等效，Generator 的优势在于可重用性和编译缓存。\n\n资料来源：[outlines/release_note.md:100-120]()\n\n## 应用示例\n\n### 客户服务工单分类\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass ServiceTicket(BaseModel):\n category: Literal[\"billing\", \"technical\", \"shipping\", \"general\"]\n priority: Literal[\"low\", \"medium\", \"high\", \"urgent\"]\n summary: str\n requires_manager: bool\n\nticket = model(prompt, ServiceTicket, max_new_tokens=500)\n\n# 根据结果路由\nif ticket.priority == \"urgent\" or ticket.requires_manager:\n alert_manager(ticket)\n```\n\n### 产品分类\n\n```python\nfrom pydantic import BaseModel\nfrom typing import List, Optional\n\nclass ProductCategory(BaseModel):\n main_category: str\n sub_category: str\n attributes: List[str]\n brand_match: Optional[str]\n\n# 处理产品描述\nproduct = \"Apple iPhone 15 Pro, 256GB, Titanium Gray\"\nresult = model(product, ProductCategory)\n```\n\n### 会议安排\n\n```python\nfrom typing import List, Optional\nfrom datetime import date\n\ndef schedule_meeting(\n title: str,\n date: date,\n duration_minutes: int,\n attendees: List[str],\n location: Optional[str] = None,\n agenda_items: Optional[List[str]] = None\n):\n # 实际应用中创建会议\n meeting = {\n \"title\": title,\n \"date\": date,\n \"duration_minutes\": duration_minutes,\n \"attendees\": attendees,\n }\n return f\"Meeting '{title}' scheduled\"\n\nresult = model(natural_language_request, schedule_meeting)\n```\n\n资料来源：[README.md:100-180]()\n\n## 部署选项\n\n### Modal 部署\n\nOutlines 支持在 Modal 平台上部署：\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n```\n\n资料来源：[examples/modal_example.py:1-20]()\n\n### BentoML 部署\n\n```python\n# requirements.txt\nbentoml>=1.2.11\noutlines==0.0.37\ntransformers==4.38.2\ndatasets==2.18.0\naccelerate==0.27.2\n```\n\n资料来源：[examples/bentoml/requirements.txt:1-5]()\n\n## 核心设计原则\n\nOutlines 的设计遵循以下原则：\n\n| 原则 | 描述 | 实现方式 |\n|-----|------|---------|\n| 类型即约束 | 期望输出通过类型指定 | Pydantic、Literal、int 等 |\n| 生成时验证 | 结构在生成过程中保证 | Logits Processor |\n| 模型抽象 | 统一接口支持多模型 | BaseModel 基类 |\n| 异步优先 | 完整异步支持 | AsyncModel 基类 |\n| 渐进式复杂度 | 从简单到复杂逐步深入 | 多种输出类型选项 |\n\n**类型即约束**的设计哲学与 Python 自身的类型系统保持一致，使得开发者可以像定义函数返回类型一样定义 LLM 输出的期望结构。\n\n资料来源：[README.md:20-35]()\n\n## 总结\n\nOutlines 是一个功能强大且设计优雅的结构化输出框架，通过以下核心能力解决了 LLM 应用开发中的关键挑战：\n\n1. **生成时结构保证**：避免生成后解析的不确定性和脆弱性\n2. **统一的模型接口**：支持多种提供商，切换模型无需修改业务代码\n3. **Pythonic 类型系统**：利用 Python 原生类型指定输出结构\n4. **灵活的输出约束**：支持 Literal、Pydantic、Regex、JSON Schema 等多种约束方式\n5. **完整的异步支持**：适配现代异步应用架构\n6. **清晰的异常层次**：便于错误处理和调试\n\nOutlines v1 版本通过引入 Generator 组件、异步模型支持和完善的类型系统，进一步提升了框架的可用性和灵活性，使其成为构建生产级 LLM 应用的理想选择。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[Outlines 简介](#page-introduction), [快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/dottxt-ai/outlines/blob/main/pyproject.toml)\n- [environment.yml](https://github.com/dottxt-ai/outlines/blob/main/environment.yml)\n- [examples/bentoml/requirements.txt](https://github.com/dottxt-ai/outlines/blob/main/examples/bentoml/requirements.txt)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n \n\n# 安装指南\n\n## 概述\n\nOutlines 是一个用于大语言模型（LLM）结构化输出的 Python 库。本指南将帮助用户在各种环境中正确安装和配置 Outlines。\n\n## 系统要求\n\n### Python 版本\n\nOutlines 需要 Python 3.10 或更高版本。\n\n```资料来源：[examples/modal_example.py:1]()[examples/bentoml/requirements.txt:4]()\n\n依赖项版本兼容性：\n- Python ≥ 3.10\n- outlines ≥ 1.0.0\n\n```\n\n## 安装方法\n\n### 使用 pip 安装（推荐）\n\n通过 pip 安装 Outlines 是最简单的方式：\n\n```bash\npip install outlines\n```\n\n资料来源：[README.md:1]()\n\n### 从源码安装\n\n对于需要最新功能或想要参与开发的用户，可以从源码安装：\n\n```bash\ngit clone https://github.com/dottxt-ai/outlines.git\ncd outlines\npip install -e .\n```\n\n## 核心依赖\n\nOutlines 的核心功能依赖于以下库：\n\n| 依赖项 | 用途 | 最低版本 |\n|--------|------|----------|\n| pydantic | 数据验证和结构定义 | - |\n| interegular | 正则表达式处理和 FSM 编译 | - |\n| numpy | 数值计算支持 | - |\n\n资料来源：[pyproject.toml](https://github.com/dottxt-ai/outlines/blob/main/pyproject.toml)\n\n## 模型后端安装\n\nOutlines 支持多种模型后端，不同的后端需要不同的依赖配置。\n\n### Transformers 后端\n\n用于本地 Hugging Face 模型，需要安装 transformers 和相关依赖：\n\n```资料来源：[README.md:1]()\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n依赖版本要求：\n```\ntransformers>=4.38.2\ndatasets>=2.18.0\naccelerate>=0.27.2\n```\n\n资料来源：[examples/bentoml/requirements.txt:3-5]()\n\n### vLLM 后端\n\n用于高效的推理服务部署：\n\n```python\nfrom outlines import from_vllm\nfrom vllm import LLM\n\nmodel = from_vllm(LLM(\"microsoft/Phi-3-mini-4k-instruct\"))\n```\n\n安装 vLLM 后端需要单独的 vLLM 库：\n\n```bash\npip install vllm\n```\n\n### OpenAI API 后端\n\n用于调用 OpenAI API 模型：\n\n```python\nimport outlines\n\nmodel = outlines.openai(\"gpt-4\")\nresult = model(\"Hello world\", str)\n```\n\n### Anthropic API 后端\n\n用于调用 Anthropic Claude 模型：\n\n```python\nimport outlines\n\nmodel = outlines.anthropic(\"claude-3-opus-20240229\")\nresult = model(\"Hello world\", str)\n```\n\n### Ollama 后端\n\n用于调用本地 Ollama 模型：\n\n```python\nfrom huggingface_hub import AsyncInferenceClient\nimport outlines\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n## 环境配置\n\n### 使用 conda 环境\n\n可以通过 environment.yml 创建完整的环境：\n\n```yaml\nname: outlines-env\ndependencies:\n - python>=3.10\n - pip\n - pip:\n - outlines\n - transformers\n - accelerate\n```\n\n创建环境命令：\n\n```bash\nconda env create -f environment.yml\nconda activate outlines-env\n```\n\n资料来源：[environment.yml](https://github.com/dottxt-ai/outlines/blob/main/environment.yml)\n\n### GPU 环境配置\n\n对于使用 GPU 进行推理的模型，需要配置 CUDA 环境：\n\n1. 确保安装 NVIDIA 驱动\n2. 安装对应版本的 CUDA Toolkit\n3. 安装 PyTorch with CUDA 支持：\n\n```bash\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121\n```\n\n## Docker 部署\n\n### 使用 Modal 部署\n\nOutlines 支持通过 Modal 进行云端部署：\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n```\n\n资料来源：[examples/modal_example.py:7-12]()\n\n### BentoML 部署\n\nOutlines 也可以通过 BentoML 进行容器化部署：\n\n依赖要求：\n```\nbentoml>=1.2.11\noutlines==0.0.37\ntransformers==4.38.2\ndatasets>=2.18.0\naccelerate>=0.27.2\n```\n\n资料来源：[examples/bentoml/requirements.txt:1-5]()\n\n## 安装验证\n\n安装完成后，可以通过以下方式验证：\n\n```python\nimport outlines\nfrom outlines import from_transformers\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n# 验证基本导入\nprint(\"Outlines 版本:\", outlines.__version__)\n\n# 验证模型加载（使用最小模型示例）\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 测试结构化输出\nfrom typing import Literal\nresult = model(\"Pizza or burger?\", Literal[\"pizza\", \"burger\"])\nprint(f\"结果: {result}\")\n```\n\n## 常见问题\n\n### 依赖冲突\n\n如果遇到依赖冲突，建议：\n\n1. 创建独立的虚拟环境\n2. 使用 `pip install --upgrade` 更新相关包\n3. 检查 Python 版本是否满足要求\n\n### CUDA 版本不兼容\n\n确保 PyTorch 版本与 CUDA 版本匹配：\n\n| CUDA 版本 | PyTorch 最低版本 |\n|-----------|------------------|\n| CUDA 11.7 | torch >= 1.13 |\n| CUDA 11.8 | torch >= 2.0 |\n| CUDA 12.1 | torch >= 2.1 |\n\n### 模型下载失败\n\n如果模型下载失败，可以：\n\n1. 设置 Hugging Face 镜像源\n2. 预先下载模型到本地目录\n3. 使用离线模式加载已缓存的模型\n\n## 版本升级\n\n### 从旧版本升级\n\n从 v0.x 升级到 v1.x 需要注意以下重大变更：\n\n| v0.x 特性 | v1.x 等效 |\n|-----------|-----------|\n| `Generator` | `Generator` 或直接调用模型 |\n| `Function` | `Application` |\n| `load_lora()` | 通过模型实例或参数传递 |\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n升级步骤：\n\n```bash\npip install --upgrade outlines\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|pip| C[pip install outlines]\n B -->|conda| D[conda env create]\n B -->|源码| E[git clone && pip install -e]\n C --> F{需要模型后端?}\n D --> F\n E --> F\n F -->|Transformers| G[安装 transformers/accelerate]\n F -->|vLLM| H[安装 vllm]\n F -->|API| I[安装 openai/anthropic SDK]\n F -->|无后端| J[仅核心功能]\n G --> K[验证安装]\n H --> K\n I --> K\n J --> K\n K --> L{验证成功?}\n L -->|是| M[安装完成]\n L -->|否| N[排查问题]\n N --> K\n```\n\n## 相关文档\n\n- [快速入门指南](README.md)\n- [模型集成](../features/models)\n- [核心功能](../features/core/generator)\n- [结构化输出类型](../features/core/ouput_types)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[Outlines 简介](#page-introduction), [输出类型](#page-output-types)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [release_note.md](https://github.com/dottxt-ai/outlines/blob/main/release_note.md)\n- [examples/dating_profile.py](https://github.com/dottext-ai/outlines/blob/main/examples/dating_profile.py)\n- [examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n \n\n# 快速开始\n\nOutlines 是一个用于在大型语言模型（LLM）生成过程中保证结构化输出的 Python 库。本页面将指导您从安装到完成第一个结构化生成任务，帮助您快速上手 Outlines 的核心功能。\n\n## 安装 Outlines\n\n### 使用 pip 安装\n\n通过 pip 安装 Outlines 的稳定版本：\n\n```shell\npip install outlines\n```\n\n资料来源：[README.md:1]()\n\n### 安装特定版本（可选）\n\n如需安装特定版本，可以使用版本号：\n\n```shell\npip install outlines==1.0.0\n```\n\n资料来源：[examples/modal_example.py:14]()\n\n## 连接模型\n\nOutlines 支持多种模型后端，包括 Transformers、OpenAI、Anthropic、Ollama、vLLM 等。以下介绍最常用的 Transformers 集成方式。\n\n### 使用 Transformers 模型\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n资料来源：[README.md:1]()\n\n### 从 v0 到 v1 的 API 变化\n\n在 v1 版本中，模型创建方式发生了重要变化：\n\n```python\n# v0 方式\nfrom outlines import models\nmodel = models.transformers(\"microsoft/Phi-3-mini-4k-instruct\")\n\n# v1 方式\nfrom outlines import from_transformers\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n```\n\n资料来源：[release_note.md:1]()\n\n## 基本结构化输出\n\nOutlines 的核心理念是直接指定输出类型，系统自动保证生成结果符合该结构。\n\n### 简单分类任务\n\n使用 `Literal` 类型进行分类：\n\n```python\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # 输出: \"Positive\"\n```\n\n资料来源：[README.md:1]()\n\n### 数值类型输出\n\n直接指定 Python 内置类型：\n\n```python\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 输出: 100\n```\n\n资料来源：[README.md:1]()\n\n## 使用 Pydantic 模型\n\n对于复杂的数据结构，使用 Pydantic 定义模型：\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n```\n\n资料来源：[README.md:1]()\n\n### 完整示例：约会资料生成\n\n以下是一个完整的结构化输出示例：\n\n```python\nimport outlines\nfrom pydantic import BaseModel\nfrom typing import Optional, List\nfrom enum import Enum\n\n\nclass MbtiType(str, Enum):\n INTJ = \"INTJ\"\n INFP = \"INFP\"\n ENTP = \"ENTP\"\n # ... 其他 MBTI 类型\n\n\nclass HobbyCategory(str, Enum):\n sports = \"sports\"\n arts = \"arts\"\n gaming = \"gaming\"\n outdoors = \"outdoors\"\n music = \"music\"\n reading = \"reading\"\n cooking = \"cooking\"\n travel = \"travel\"\n\n\nclass DatingProfile(BaseModel):\n name: str\n age: int\n gender: str\n mbti: MbtiType\n location: str\n height: int\n bio: str\n hobbies: List[HobbyCategory]\n preferred_gender: str\n preferred_age_range: str\n personality_traits: List[str]\n\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n\nprofile = model(\"Create a dating profile for a 28-year-old software engineer in San Francisco\", DatingProfile)\nprint(profile)\n```\n\n资料来源：[examples/dating_profile.py:1]()\n\n## 使用模板\n\nOutlines 支持 Jinja 模板，便于动态生成提示词：\n\n```python\nimport outlines\n\n# 从字符串创建模板\nsentiment_template = outlines.Template.from_string(\"\"\"\n<|im_start|>user\nAnalyze the sentiment of the following {{ content_type }}:\n\n{{ text }}\n\nProvide your analysis as either \"Positive\", \"Negative\", or \"Neutral\".\n<|im_end>\n<|im_start|>assistant\n\"\"\")\n\n# 使用模板生成提示词\nreview = \"This restaurant exceeded all my expectations. Fantastic service!\"\nprompt = sentiment_template(content_type=\"review\", text=review)\n\n# 使用模板进行结构化生成\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md:1]()\n\n### 从文件加载模板\n\n```python\n# 从文件加载模板\nexample_template = outlines.Template.from_file(\"templates/few_shot.txt\")\n```\n\n资料来源：[README.md:1]()\n\n## ReAct 模式\n\nOutlines 支持 ReAct（Reasoning + Acting）模式，实现链式推理和工具调用：\n\n```python\ndef search_wikipedia(query: str) -> str:\n \"\"\"模拟 Wikipedia 搜索\"\"\"\n # 实际实现中会调用 Wikipedia API\n return f\"Results for: {query}\"\n\ndef add_mode(i: int, mode: str, result: str, prompt: str) -> str:\n \"\"\"添加观察结果到提示词\"\"\"\n return prompt + f\"\\n{i}. {mode}: {result}\\n\"\n\n# 初始化\nprompt = \"Apple Computers\"\nmode = \"Thought\"\n\n# ReAct 循环\nfor i in range(3):\n thought = _generator(prompt, stop=[\"'\"], max_tokens=128)\n \n if \"Search\" in thought:\n subject = \" \".join(thought.split()[:2])\n result = search_wikipedia(subject)\n prompt = add_mode(i=i, mode=\"Obs\", result=result, prompt=prompt)\n else:\n break\n```\n\n资料来源：[examples/react.py:1]()\n\n## 生成器模式\n\n使用 `Generator` 类可以创建可重用的生成器，避免重复编译：\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 创建生成器\ngenerator = Generator(model, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n\n# 多次使用，无需重复指定输出类型\nresult1 = generator(\"This movie was amazing!\")\nresult2 = generator(\"The food was terrible.\")\n```\n\n资料来源：[release_note.md:1]()\n\n## 完整工作流程图\n\n```mermaid\ngraph TD\n A[安装 Outlines] --> B[选择模型后端]\n B --> C{模型类型}\n C -->|Transformers| D[使用 from_transformers]\n C -->|OpenAI| E[使用 from_openai]\n C -->|vLLM| F[使用 from_vllm]\n D --> G[定义输出类型]\n E --> G\n F --> G\n G --> H{复杂度}\n H -->|简单类型| I[使用 Literal 或内置类型]\n H -->|复杂结构| J[使用 Pydantic 模型]\n I --> K[调用 model 生成]\n J --> K\n K --> L[获得结构化输出]\n```\n\n## 快速参考表\n\n| 场景 | 输出类型 | 示例 |\n|------|----------|------|\n| 二分类 | `Literal[\"Yes\", \"No\"]` | 情感判断 |\n| 多分类 | `Literal[\"A\", \"B\", \"C\"]` | 主题分类 |\n| 整数 | `int` | 数量提取 |\n| 浮点数 | `float` | 温度提取 |\n| 复杂对象 | `BaseModel` | JSON 结构 |\n\n## 常见问题\n\n### 模型调用方式变化\n\nv1 版本支持直接调用模型，无需先创建生成器：\n\n```python\n# v1 直接调用\nresult = model(\"prompt\", output_type)\n\n# 或使用生成器（推荐重复使用场景）\ngenerator = Generator(model, output_type)\nresult = generator(\"prompt\")\n```\n\n### JSON Schema 支持\n\n可以使用 `JsonSchema` 类型直接指定 JSON Schema：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2? Respond in a json\", JsonSchema(json_schema))\n```\n\n资料来源：[release_note.md:1]()\n\n## 下一步\n\n- 阅读[安装指南](./guide/installation.md)了解更详细的安装选项\n- 查看[架构文档](./guide/architecture.md)深入了解 Outlines 工作原理\n- 探索[功能文档](./features/index.md)学习更多高级用法\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心概念](#page-core-concepts), [后端系统](#page-backends)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/processors/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/processors/__init__.py)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n \n\n# 系统架构\n\n## 概述\n\nOutlines 是一个保证大型语言模型（LLM）输出结构化的框架。其核心设计理念是通过类型驱动的 API，让用户在调用模型时直接指定期望的输出类型（如 `Literal[\"Yes\", \"No\"]`、`int` 或 Pydantic 模型），Outlines 会在生成过程中强制保证输出符合该结构。\n\n该框架的核心价值在于**生成时约束**（而不是生成后解析），这避免了传统方法中依赖正则表达式或脆弱解析逻辑所带来的问题。\n\n资料来源：[README.md]()\n\n## 架构分层\n\nOutlines 采用分层架构设计，各层职责清晰，从用户 API 到底层模型提供者形成单向依赖关系：\n\n```mermaid\ngraph TD\n A[用户 API
outlines.models] --> B[生成器类
SteerableGenerator
BlackBoxGenerator]\n B --> C[类型系统
types/dsl.py
Pydantic → JsonSchema → Regex]\n C --> D[FSM 编译
outlines-core
regex → FSM via interegular]\n D --> E[引导系统
processors/guide.py
FSM 状态管理]\n E --> F[Logits 处理
processors/structured.py
Token 掩码]\n F --> G[模型提供者
transformers
OpenAI
vLLM
Ollama]\n```\n\n资料来源：[llm.txt]()\n\n### 层级职责说明\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 用户 API | `outlines.models` | 提供统一的模型调用接口 |\n| 生成器 | `Generator`, `SteerableGenerator`, `BlackBoxGenerator` | 管理生成逻辑和输出类型编译 |\n| 类型系统 | `types/dsl.py` | 将 Python 类型转换为内部表示 |\n| FSM 编译 | `outlines-core` | 将正则表达式编译为有限状态机 |\n| 引导系统 | `processors/guide.py` | 管理 FSM 状态和有效 Token |\n| Logits 处理 | `processors/structured.py` | 通过 Token 掩码强制约束 |\n| 模型提供者 | transformers, OpenAI 等 | 与具体模型 API 交互 |\n\n资料来源：[llm.txt]()\n\n## 核心组件\n\n### 模型层 (`outlines/models/`)\n\n#### 模型基类设计\n\n模型层包含两个核心基类，分别对应不同类型的模型：\n\n| 基类 | 适用场景 | 控制方式 |\n|------|----------|----------|\n| `SteerableModel` | 本地模型（transformers, llama.cpp） | 直接控制 logits |\n| `BlackBoxModel` | API 模型（OpenAI, Anthropic） | 利用提供商的原生结构化输出支持 |\n\n#### 异步支持\n\nv1.0 版本新增了对异步操作的支持，新增了三个异步模型类：\n\n- `AsyncSGLang`\n- `AsyncTGI`\n- `AsyncVLLM`\n\n```python\nfrom outlines import from_tgi\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n资料来源：[outlines/release_note.md]()\n\n#### 异步方法接口\n\n所有模型类都实现了以下异步方法：\n\n| 方法 | 功能 | 返回类型 |\n|------|------|----------|\n| `async stream(...)` | 异步流式生成 | `AsyncIterator[Any]` |\n| `async batch(...)` | 异步批量生成 | `List[Any]` |\n| `async __call__(...)` | 异步单次调用 | `Any` |\n\n```python\n# 流式调用等效方式\ngenerator = Generator(model, Foo)\nasync for chunk in generator(\"prompt\"):\n print(chunk)\n\n# 直接调用模型\nasync for chunk in model.stream(\"prompt\", Foo):\n print(chunk)\n\n# 等效的异步调用\nawait model(\"prompt\", Foo)\n```\n\n资料来源：[outlines/models/base.py]()\n\n### 生成器层\n\n#### Generator 类\n\n`Generator` 是 Outlines v1.0 引入的核心组件，用于封装模型和输出类型的组合：\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ngenerator = Generator(model, int)\nresult = generator(\"What's 2 + 2?\")\n```\n\n生成器的优势在于：\n- **可复用性**：无需每次调用都指定输出类型\n- **延迟编译**：输出类型的 FSM 编译只在首次使用时执行一次\n- **持久缓存**：编译结果会被缓存\n\n资料来源：[outlines/release_note.md]()\n\n#### 生成器类型\n\n| 类型 | 适用模型 | 约束实现方式 |\n|------|----------|--------------|\n| `SteerableGenerator` | 本地模型 | FSM + Logits 掩码 |\n| `BlackBoxGenerator` | API 模型 | 提供商原生结构化输出 |\n\n### 类型系统\n\n类型系统负责将 Python 类型转换为内部约束表示：\n\n```mermaid\ngraph LR\n A[Python 类型] --> B[Pydantic 模型]\n A --> C[Literal 类型]\n A --> D[JsonSchema]\n A --> E[Regex/CFG]\n B --> F[JsonSchema]\n C --> G[正则表达式]\n D --> G\n E --> G\n F --> H[FSM]\n G --> H\n```\n\n#### 支持的类型格式\n\n| 类型格式 | 示例 | 说明 |\n|----------|------|------|\n| `Literal` | `Literal[\"Yes\", \"No\"]` | 枚举值约束 |\n| `int` / `float` | `int` | 数值类型约束 |\n| `Pydantic` | `BaseModel` 子类 | 复杂对象结构 |\n| `JsonSchema` | `{\"type\": \"object\", ...}` | JSON Schema 格式 |\n| `Regex` | `Regex(r\"\\d+\")` | 正则表达式约束 |\n| `CFG` | 上下文无关文法 | 形式文法约束 |\n\n资料来源：[outlines/release_note.md]()\n\n### FSM 编译层\n\nFSM（有限状态机）是 Outlines 实现结构化生成的核心机制：\n\n```mermaid\ngraph LR\n A[正则表达式] -->|interegular| B[FSM]\n B --> C[状态转换表]\n C --> D[有效 Token 集合]\n```\n\n**工作流程**：\n1. 用户指定输出类型（如 `Literal[\"Yes\", \"No\"]`）\n2. 类型系统将其转换为正则表达式\n3. 正则表达式通过 `interegular` 库编译为 FSM\n4. FSM 在生成过程中追踪有效状态\n\n资料来源：[llm.txt]()\n\n### 引导系统 (`processors/guide.py`)\n\n引导系统负责管理 FSM 状态并计算每个时间步的有效 Token：\n\n```mermaid\ngraph TD\n A[当前 Token] --> B[FSM 状态更新]\n B --> C{终止状态?}\n C -->|是| D[停止生成]\n C -->|否| E[计算有效 Token]\n E --> F[掩码 Logits]\n F --> G[采样下一 Token]\n G --> A\n```\n\n关键特性：\n- **Token 级控制**：约束作用于 Token 级别，而非字符级别\n- **状态追踪**：维护 FSM 的当前状态\n- **动态掩码**：根据有效 Token 集合屏蔽无效 Token\n\n资料来源：[llm.txt]()\n\n### 异常处理 (`outlines/exceptions.py`)\n\nOutlines 定义了完整的异常层次结构：\n\n```mermaid\ngraph TD\n A[Exception] --> B[OutlinesError]\n B --> C[APIError]\n C --> D[AuthenticationError]\n C --> E[PermissionDeniedError]\n C --> F[NotFoundError]\n C --> G[RateLimitError]\n C --> H[BadRequestError]\n C --> I[ServerError]\n C --> J[APITimeoutError]\n C --> K[APIConnectionError]\n B --> L[ProviderResponseError]\n B --> M[GenerationError]\n```\n\n#### 异常类属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `provider` | `str \\| None` | 提供商名称（如 \"openai\"） |\n| `original_exception` | `Exception \\| None` | 原始 SDK 异常 |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 请求 ID（用于问题追踪） |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 人类可读的建议信息 |\n\n资料来源：[outlines/exceptions.py]()\n\n## 关键设计决策\n\n### 1. FSM 基础约束\n\n对于本地模型，约束被编译为有限状态机，用于追踪有效下一个 Token。这种方法确保了生成过程严格遵守结构规范。\n\n资料来源：[llm.txt]()\n\n### 2. 提供商抽象\n\n统一的约束系统同时支持本地模型（transformers）和 API 模型（OpenAI）。对于 API 模型，Outlines 会利用提供商原生的结构化输出功能（如 OpenAI 的 JSON Mode）。\n\n资料来源：[README.md]()\n\n### 3. 延迟编译\n\nFSM 在首次使用时编译并持久缓存，避免了重复编译的开销。\n\n```python\n# 首次调用时编译 FSM\nresult = model(\"What's 2 + 2?\", int) # 编译发生在此时\n\n# 后续调用使用缓存\nresult = model(\"What's 3 + 3?\", int) # 使用缓存的 FSM\n```\n\n资料来源：[outlines/release_note.md]()\n\n### 4. 类型驱动 API\n\nPython 类型是指定约束的主要接口，与 Python 自身的类型系统保持一致：\n\n| 需求 | 类型指定方式 |\n|------|--------------|\n| 是/否回答 | `Literal[\"Yes\", \"No\"]` |\n| 数值 | `int` |\n| 复杂对象 | Pydantic 模型 |\n\n资料来源：[README.md]()\n\n## 模型集成\n\n### 支持的模型提供商\n\n| 提供商 | 模型类 | 特点 |\n|--------|--------|------|\n| Transformers | `Transformers` | 本地模型，完整控制 |\n| OpenAI | `OpenAI` | API 调用 |\n| Anthropic | `Anthropic` | API 调用 |\n| Ollama | `Ollama` | 本地模型 |\n| vLLM | `VLLM` | 高性能本地推理 |\n| SGLang | `SGLang` | 高性能本地推理 |\n| TGI | `TGI` | Hugging Face 推理端点 |\n| Llama.cpp | `LlamaCpp` | CPU 高效推理 |\n| Gemini | `Gemini` | Google AI 模型 |\n\n### 模型初始化示例\n\n```python\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\", device_map=\"auto\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"Analyze: 'Great product!'\", Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md]()\n\n## LoRA 支持变化\n\nv1.0 版本对 LoRA 加载方式进行了调整：\n\n| 版本 | 方式 | 示例 |\n|------|------|------|\n| v0 | `model.load_lora(path)` | 直接在模型上调用 |\n| v1 | 参数传递 | `response = model(..., lora_request=lora_request)` |\n\n```python\nfrom outlines import from_vllm\nfrom vllm import LLM\nfrom vllm.lora.request import LoRARequest\n\nmodel = from_vllm(LLM(\"microsoft/Phi-3-mini-4k-instruct\"))\nlora_request = LoRARequest(\"lora_name\", 1, \"path/to/lora/file\")\nresponse = model(\"Write a short story.\", lora_request=lora_request)\n```\n\n资料来源：[outlines/release_note.md]()\n\n## 弃用说明\n\n### v1.0 弃用的功能\n\n| 组件 | 替代方案 | 原因 |\n|------|----------|------|\n| `Exllamav2` 模型 | 无替代 | 接口不兼容，维护成本高 |\n| `Function` 类 | `Application` 类 | 更清晰的职责分离 |\n| `Generator.load_lora()` | 模型初始化参数或调用参数 | 统一的 LoRA 管理方式 |\n\n#### Function 到 Application 的迁移\n\n```python\n# v0\nfrom outlines import Function, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\nfn = Function(template, Character, \"hf-internal-testing/tiny-random-GPTJForCausalLM\")\nresponse = fn(gender=\"female\")\n\n# v1\nfrom outlines import Application, Template, from_transformers\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\nresponse = app(model, {\"gender\": \"female\"})\n```\n\n资料来源：[outlines/release_note.md]()\n\n## 总结\n\nOutlines 的系统架构通过分层设计实现了灵活且强大的结构化生成能力：\n\n1. **统一 API**：用户通过简单的类型指定即可约束输出\n2. **高效编译**：延迟编译和持久缓存优化性能\n3. **广泛兼容**：支持多种模型提供商的统一接口\n4. **清晰职责**：各层职责分明，便于维护和扩展\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [后端系统](#page-backends)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n \n\n# 核心概念\n\nOutlines 是一个保证 LLM 输出的结构化生成库。其核心理念是：在生成过程中直接约束输出格式，而不是在生成后通过解析、Regex 或脆弱的代码来修复不良输出。\n\n## 设计理念\n\n### 问题与解决方案\n\n传统的 LLM 输出处理方式存在以下问题：\n\n| 方法 | 问题 |\n|------|------|\n| 解析 (Parsing) | 输出可能不遵循预期格式 |\n| Regex 匹配 | 脆弱且难以维护 |\n| 后处理代码 | 容易在边界情况下失败 |\n\nOutlines 的解决方案是**在生成过程中直接保证结构有效性**，确保输出从一开始就是正确的格式。\n\n### Outlines 哲学\n\nOutlines 遵循一个简单的模式，模仿 Python 自身的类型系统。只需指定期望的输出类型，Outlines 就会确保数据完全匹配该结构：\n\n- 对于是/否响应，使用 `Literal[\"Yes\", \"No\"]`\n- 对于数值，使用 `int` 或 `float`\n- 对于复杂对象，使用 Pydantic 模型定义结构\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n A[用户代码] --> B[output_type]\n A --> C[prompt]\n end\n \n subgraph \"核心层\"\n B --> D[Generator]\n C --> D\n D --> E[Logits 处理器]\n end\n \n subgraph \"后端层\"\n E --> F[Transformers]\n E --> G[VLLM]\n E --> H[OpenAI]\n E --> I[Anthropic]\n E --> J[LlamaCpp]\n end\n \n subgraph \"模型层\"\n F --> K[本地模型]\n G --> L[vLLM Server]\n H --> M[OpenAI API]\n I --> N[Anthropic API]\n J --> O[本地 GGUF]\n end\n```\n\n资料来源：[outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## 输出类型系统\n\nOutlines 支持多种输出类型，用于约束生成内容的结构：\n\n### 基础类型\n\n| 类型 | 说明 | 示例 |\n|------|------|------|\n| `int` | 整数 | `model(\"What's 2+2?\", int)` |\n| `float` | 浮点数 | `model(\"Temperature?\", float)` |\n| `str` | 字符串 | `model(\"Name?\", str)` |\n\n### Literal 类型\n\n用于有限的选项集合：\n\n```python\nfrom typing import Literal\n\nresult = model(\"Sentiment?\", Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Pydantic 模型\n\n用于复杂结构化数据：\n\n```python\nfrom pydantic import BaseModel\n\nclass ProductReview(BaseModel):\n rating: int\n pros: list[str]\n cons: list[str]\n```\n\n### Regex 和 DSL\n\n```python\nfrom outlines.types import JsonSchema, Regex, integer\n\n# 使用 JSON Schema\nresult = model(\"Answer in JSON\", JsonSchema(schema))\n\n# 使用正则表达式\npattern = Regex(r\"^[\\d]{3}-[\\d]{4}$\")\nphone = model(\"Phone?\", pattern)\n```\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## 模型集成\n\nOutlines 支持多种模型后端，提供统一的调用接口：\n\n### 支持的模型类型\n\n| 模型类型 | 说明 | 文档链接 |\n|----------|------|----------|\n| `Transformers` | Hugging Face 本地模型 | 资料来源：[examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py) |\n| `OpenAI` | OpenAI API 模型 | - |\n| `Anthropic` | Anthropic Claude 模型 | - |\n| `VLLM` | vLLM 服务端 | - |\n| `LlamaCpp` | 本地 GGUF 格式模型 | - |\n| `Gemini` | Google Gemini 模型 | 资料来源：[outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py) |\n| `SGLang` | SGLang 服务端 | - |\n\n### 异步模型支持\n\n异步模型提供高性能的批量推理能力：\n\n```python\nfrom outlines import from_tgi\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(\n AsyncInferenceClient(\"http://localhost:11434\")\n)\n```\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Generator 类\n\nGenerator 是 Outlines v1 的核心组件，用于封装模型和输出类型的组合：\n\n### 特性\n\n- **可重用性**：一次编译，多次生成\n- **延迟编译**：输出类型的编译只在第一次生成时进行\n- **统一接口**：支持同步和异步调用\n\n### 使用方式\n\n```python\nfrom outlines import Generator, from_transformers\nfrom typing import Literal\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 直接调用\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n\n# 使用 Generator\ngenerator = Generator(model, Literal[\"pizza\", \"burger\"])\nresult = generator(\"What's your favorite food?\")\n```\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## 模型基类接口\n\nBaseModel 类提供了统一的模型调用接口：\n\n### 核心方法\n\n| 方法 | 说明 |\n|------|------|\n| `__call__` | 同步生成单个响应 |\n| `stream` | 流式生成响应 |\n| `batch` | 批量生成多个响应 |\n\n### 异步方法\n\n```python\nasync def stream(\n self,\n model_input: Any,\n output_type: Optional[Any] = None,\n backend: Optional[str] = None,\n **inference_kwargs: Any\n) -> AsyncIterator[Any]\n```\n\n```python\nasync def batch(\n self,\n model_input: List[Any],\n output_type: Optional[Any] = None,\n backend: Optional[str] = None,\n **inference_kwargs: Any\n) -> List[Any]\n```\n\n资料来源：[outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## 异常处理\n\nOutlines 提供了完整的异常层次结构：\n\n### 异常层次\n\n```\nOutlinesError\n├── APIError\n│ ├── AuthenticationError\n│ ├── PermissionDeniedError\n│ ├── NotFoundError\n│ ├── RateLimitError\n│ ├── BadRequestError\n│ ├── ServerError\n│ ├── APITimeoutError\n│ ├── APIConnectionError\n│ └── ProviderResponseError\n└── GenerationError\n```\n\n### APIError 特性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `provider` | `str \\| None` | 提供商名称（如 \"openai\"） |\n| `original_exception` | `Exception \\| None` | 原始 SDK 异常 |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 提供商请求 ID |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 人类可读的建议 |\n\n资料来源：[outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n## 应用场景\n\n### 函数调用\n\nOutlines 可以将自然语言转换为结构化函数调用：\n\n```python\ndef schedule_meeting(\n title: str,\n date: date,\n duration_minutes: int,\n attendees: List[str],\n location: Optional[str] = None\n):\n \"\"\"安排会议\"\"\"\n return f\"会议 '{title}' 已安排\"\n\nresult = model(\n \"I need to set up a meeting tomorrow at 2pm with Alice and Bob\",\n schedule_meeting\n)\n```\n\n### 模板系统\n\n使用 Jinja 模板生成动态提示：\n\n```python\ntemplate = outlines.Template.from_string(\"\"\"\n<|im_start|>user\n分析以下 {{ content_type }}的情感：\n\n{{ text }}\n<|im_end|>\n\"\"\")\n\nprompt = template(content_type=\"review\", text=\"Great product!\")\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### ReAct 模式\n\n实现 ReAct（Reasoning + Acting）模式：\n\n```python\ndef react_generator(prompt, stop=None, max_tokens=128):\n while True:\n response = llm(prompt, max_tokens=max_tokens)\n # 解析 action 和 action_input\n # 执行 action\n # 更新 prompt\n```\n\n资料来源：[examples/react.py](https://github.com/dottxt-ai/outlines/blob/main/examples/react.py)\n\n## 快速开始\n\n### 1. 安装\n\n```shell\npip install outlines\n```\n\n### 2. 连接模型\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n```\n\n### 3. 结构化生成\n\n```python\nfrom typing import Literal\n\n# 分类\nsentiment = model(\"分析: '这个产品彻底改变了我的生活！'\", \n Literal[\"Positive\", \"Negative\", \"Neutral\"])\n\n# 提取数字\ntemperature = model(\"水的沸点是多少摄氏度？\", int)\n```\n\n资料来源：[README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n## 版本迁移说明\n\n### v0 到 v1 的主要变化\n\n| 旧版本 (v0) | 新版本 (v1) |\n|-------------|--------------|\n| `Function` 类 | `Application` 类 |\n| 关键字参数传模板变量 | 字典传模板变量 |\n| `load_lora()` 方法 | 直接传入 `LoRARequest` |\n| 模型需先创建生成器 | 模型可直接调用 |\n\n### 废弃的功能\n\n- `Exllamav2` 模型（接口不兼容）\n- `Function` 类（由 `Application` 替代）\n- 某些 `load_lora` 方法\n\n资料来源：[outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n---\n\n\n\n## 输出类型\n\n### 相关页面\n\n相关主题：[类型系统](#page-type-system), [生成器系统](#page-generator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/types/json_schema_utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/json_schema_utils.py)\n- [outlines/types/utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/utils.py)\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n \n\n# 输出类型\n\n## 概述\n\n输出类型（Output Types）是 Outlines 框架的核心概念之一，用于在 LLM 生成过程中约束输出结构，确保模型生成的文本符合预定义的格式规范。Outlines 将用户友好的 Python 类型（如 Pydantic 模型、Literal 类型、内置类型）转换为底层约束机制（正则表达式、FSM），在 token 级别控制生成过程。\n\n输出类型系统的设计遵循\"类型驱动 API\"原则：用户只需指定期望的输出类型，Outlines 自动处理约束编译和 token 掩码逻辑。\n\n## 核心类型体系\n\nOutlines 支持多种输出类型，按功能可分为以下几类：\n\n### 内置 Python 类型\n\n| 类型 | 说明 | 示例 |\n|------|------|------|\n| `int` | 整数类型 | `model(\"数字\", int)` → `42` |\n| `float` | 浮点数类型 | `model(\"温度\", float)` → `98.6` |\n| `str` | 字符串类型 | `model(\"名称\", str)` → `\"Alice\"` |\n\n### 字面量类型（Literal）\n\n用于生成预定义选项之一：\n\n```python\nfrom typing import Literal\n\nresult = model(\n \"分析情感：'产品很棒！'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\n```\n\n### Pydantic 模型\n\n复杂结构化输出的首选方式：\n\n```python\nfrom pydantic import BaseModel\n\nclass ProductReview(BaseModel):\n rating: int\n pros: list[str]\n cons: list[str]\n recommended: bool\n\nreview = model(\"分析评论...\", ProductReview)\n```\n\n### 正则表达式 DSL\n\n通过 `Regex`、`String`、`integer` 等 Term 类构建正则约束：\n\n```python\nfrom outlines.types import Regex, either, at_least\n\n# 简单正则\npattern = Regex(r\"[A-Z]{2}\\d{4}\")\n\n# 组合正则\ncomplex_pattern = either(\"yes\", \"no\", \"maybe\")\n```\n\n## 架构设计\n\n### 类型转换流程\n\n```mermaid\ngraph TD\n A[Python Type] --> B[Term Classes]\n B --> C[正则表达式]\n C --> D[FSM 编译]\n D --> E[Logits Processor]\n E --> F[Token Masking]\n F --> G[结构化生成]\n\n B --> B1[JsonSchema]\n B --> B2[CFG]\n B --> B3[Alternatives]\n B --> B4[KleeneStar]\n B --> B5[Literal Term]\n```\n\nOutlines 将输出类型处理分为三个逻辑阶段（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n1. **Term 类定义**：包含 JsonSchema、CFG 等独立使用的类型，以及组成正则 DSL 的 Alternatives、KleeneStar 等类\n2. **Python 类型到 Term 实例的转换**（`python_types_to_terms` 函数）\n3. **Term 实例到正则表达式的转换**（`to_regex` 函数）\n\n### Term 类层次\n\n```\nTerm (基类)\n├── JsonSchema # JSON Schema 约束\n├── CFG # 上下文无关文法\n├── LiteralTerm # 字面量值\n├── Regex # 正则表达式模式\n├── String # 字符串模式\n├── Integer # 整数模式\n├── Float # 浮点数模式\n├── Alternatives # 或运算 (|)\n├── Sequence # 序列连接\n├── KleeneStar # 零或多次 (*)\n├── Optional # 可选 (? 隐式)\n└── Group # 分组 (...)\n```\n\n## JSON Schema 支持\n\n### JsonSchema 类型\n\n可以直接使用 JSON Schema 字符串作为输出类型（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"2+2等于几？\", JsonSchema(json_schema))\n```\n\n### Schema 转换工具\n\n`json_schema_utils.py` 提供了 JSON Schema 与 Python 类型之间的双向转换：\n\n| 函数 | 功能 |\n|------|------|\n| `json_schema_dict_to_pydantic` | JSON Schema → Pydantic 模型 |\n| `json_schema_dict_to_typeddict` | JSON Schema → TypedDict |\n| `json_schema_dict_to_dataclass` | JSON Schema → Dataclass |\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_pydantic\n\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"age\": {\"type\": \"integer\"}\n }\n}\n\nPydanticModel = json_schema_dict_to_pydantic(schema)\n```\n\n## 正则表达式 DSL\n\n### Term 函数\n\nOutlines 提供了构建复杂正则模式的组合函数（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n| 函数 | 说明 | 示例 |\n|------|------|------|\n| `either(*items)` | 或运算 | `either(\"yes\", \"no\")` |\n| `optional(term)` | 可选 | `optional(\"maybe\")` |\n| `at_least(n, term)` | 至少 n 次 | `at_least(3, digit)` |\n| `integer()` | 整数模式 | 匹配 `-123`, `0`, `456` |\n| `float_number()` | 浮点数模式 | 匹配 `-1.5`, `3.14` |\n\n### 组合示例\n\n```python\nfrom outlines.types import either, optional, at_least, integer\n\n# 复杂模式：电话号码\nphone = either(\"+1\", \"+86\", \"\") + at_least(10, digit)\n\n# 组合多个 Term\nstatus = either(\"pending\", \"approved\", optional(\"rejected\"))\n```\n\n## 类型推断与验证\n\n### Python 类型检测\n\n`utils.py` 提供了类型检测工具函数（资料来源：[outlines/types/utils.py]()）：\n\n| 函数 | 功能 |\n|------|------|\n| `is_int(tp)` | 检测是否为整数类型 |\n| `is_int_instance(val)` | 检测值是否为整数 |\n| `is_float(tp)` | 检测是否为浮点类型 |\n| `is_str(tp)` | 检测是否为字符串类型 |\n| `get_schema_from_signature(fn)` | 从函数签名提取 schema |\n\n### Pydantic 集成\n\nOutlines 利用 Pydantic 的 `GetCoreSchemaHandler` 和 `GetJsonSchemaHandler` 实现类型适配（资料来源：[outlines/types/dsl.py:1-30]()）：\n\n```python\nclass CustomType(BaseModel):\n value: str\n \n @classmethod\n def __get_pydantic_core_schema__(cls, source, handler):\n # 自定义 schema 处理逻辑\n return handler.generate_schema(cls)\n```\n\n## 与 Generator 的集成\n\n### Generator 类\n\nGenerator 是输出类型的消费者，它接收模型和输出类型，返回可复用的生成器实例（资料来源：[outlines/models/base.py:1-50]()）：\n\n```python\nfrom outlines import Generator, from_transformers\n\nmodel = from_transformers(...)\ngenerator = Generator(model, MyOutputType)\n\n# 复用编译结果\nresult1 = generator(\"prompt1\")\nresult2 = generator(\"prompt2\")\n```\n\n### Backend 选择\n\n不同输出类型可选择不同的 backend 实现（资料来源：[outlines/backends/__init__.py:1-50]()）：\n\n| Backend | 适用类型 | 特点 |\n|---------|----------|------|\n| `outlines_core` | Regex, JSON Schema | 通用实现 |\n| `xgrammar` | JSON Schema | 高性能 |\n| `llguidance` | Regex | 快速 FSM 编译 |\n\n```python\n# 指定 backend\nresult = model(\"prompt\", MySchema, backend=\"xgrammar\")\n```\n\n## 工作流程示例\n\n### 完整生成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Model as 模型实例\n participant Generator as Generator\n participant Backend as Backend\n participant FSM as FSM 编译器\n\n User->>Model: model(prompt, OutputType)\n Model->>Generator: 创建 Generator(model, OutputType)\n Generator->>Backend: get_logits_processor(OutputType)\n Backend->>FSM: 编译约束为 FSM\n FSM-->>Backend: FSM 状态机\n Backend-->>Generator: LogitsProcessor\n Generator-->>Model: 返回处理后的响应\n Model-->>User: 结构化输出结果\n```\n\n### 实际代码示例\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\nimport outlines\n\n# 定义输出结构\nclass AnalysisResult(BaseModel):\n sentiment: Literal[\"positive\", \"negative\", \"neutral\"]\n confidence: float\n keywords: list[str]\n\n# 使用模型生成\nmodel = outlines.from_transformers(...)\nresult = model(\"这个产品太棒了！\", AnalysisResult)\n\n# result 自动类型化为 AnalysisResult 实例\nprint(result.sentiment) # \"positive\"\n```\n\n## 最佳实践\n\n### 1. 优先使用 Pydantic 模型\n\n对于复杂结构，Pydantic 模型比原始 JSON Schema 更易维护：\n\n```python\n# 推荐\nclass Response(BaseModel):\n answer: str\n confidence: float\n\n# 而非\nschema = '{\"type\": \"object\", \"properties\": {\"answer\": {...}}}'\n```\n\n### 2. 善用 Literal 约束\n\n在分类任务中使用 Literal 限制输出范围：\n\n```python\nresult = model(prompt, Literal[\"A\", \"B\", \"C\", \"D\"])\n```\n\n### 3. 组合使用 DSL\n\n构建特定格式时使用正则 DSL：\n\n```python\nfrom outlines.types import Regex, either\n\ndate_pattern = Regex(r\"\\d{4}-\\d{2}-\\d{2}\")\n```\n\n## 总结\n\n输出类型系统是 Outlines 实现结构化生成的核心抽象层。它通过将 Python 类型系统与底层 FSM 约束机制解耦，为用户提供了简洁直观的 API。核心设计包括：\n\n- **类型驱动**：以 Python 类型作为主要约束规范\n- **多层转换**：类型 → Term → 正则 → FSM\n- **灵活组合**：支持嵌套、组合多种约束类型\n- **后端抽象**：允许针对不同场景选择最优实现\n\n开发者只需关注期望的输出结构，Outlines 自动处理底层约束编译和 token 掩码逻辑。\n\n---\n\n\n\n## 类型系统\n\n### 相关页面\n\n相关主题：[输出类型](#page-output-types), [核心概念](#page-core-concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/types/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/__init__.py)\n- [outlines/grammars/json.lark](https://github.com/dottxt-ai/outlines/blob/main/outlines/grammars/json.lark)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n \n\n# 类型系统\n\n## 概述\n\nOutlines 的类型系统是整个框架的核心基础设施，负责将 Python 类型声明转换为结构化生成的约束条件。该系统采用分层架构设计，从用户友好的 Python 类型逐步编译为底层的有限状态机（FSM），最终在 token 级别控制模型输出的有效性。\n\n类型系统的主要职责包括：\n\n- **类型到约束的转换**：将 Pydantic 模型、`Literal` 类型、`int`、`str` 等 Python 类型转换为正则表达式或 FSM\n- **术语（Term）DSL**：提供 `Regex`、`JsonSchema`、`CFG` 等术语类型，支持复杂输出规范的构建\n- **JSON Schema 处理**：支持 JSON Schema 格式的输出规范定义\n- **上下文无关文法（CFG）**：支持基于文法的结构化输出约束\n\n资料来源：[outlines/types/dsl.py:1-50]()\n\n## 核心架构\n\n### 类型系统分层设计\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 用户层 (User API) │\n│ Pydantic BaseModel / Literal / int / JsonSchema / CFG │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 术语层 (Term Layer) │\n│ Term 类: JsonSchema, CFG, Regex, String, ... │\n│ 组合函数: either, optional, at_least, ... │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 正则表达式层 (Regex Layer) │\n│ to_regex() → Python re.Pattern 对象 │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ FSM 编译层 (outlines-core) │\n│ build_regex_from_schema() → FSM │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Logits 处理层 │\n│ 处理器/guide.py: FSM 状态管理与 token 掩码 │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 类型转换流程\n\n```mermaid\ngraph LR\n A[Python 类型] --> B[Term 实例
python_types_to_terms]\n B --> C[正则表达式
to_regex]\n C --> D[FSM 有限状态机
outlines-core]\n D --> E[Token 掩码
Logits Processor]\n E --> F[结构化输出]\n \n A1[Pydantic Model] --> A\n A2[Literal Type] --> A\n A3[int / float] --> A\n A4[JsonSchema] --> B\n A5[CFG 文法] --> B\n```\n\n## 核心组件详解\n\n### 术语类（Term Classes）\n\n类型系统中的所有术语类都继承自统一接口，支持转换为正则表达式。核心术语类包括：\n\n| 术语类 | 用途 | 源码位置 |\n|--------|------|----------|\n| `JsonSchema` | 基于 JSON Schema 的输出约束 | [dsl.py:50-80]() |\n| `CFG` | 上下文无关文法约束 | [dsl.py:80-110]() |\n| `Regex` | 直接使用正则表达式模式 | [dsl.py:110-140]() |\n| `String` | 字符串字面量约束 | [dsl.py:140-170]() |\n| `Alternatives` | 多选一约束（对应正则 `\\|`） | [dsl.py:170-200]() |\n| `KleeneStar` | 零次或多次重复（对应 `*`） | [dsl.py:200-230]() |\n| `Optional` | 可选约束（对应 `?`） | [dsl.py:230-260]() |\n\n### DSL 组合函数\n\n类型系统提供了丰富的组合函数，用于构建复杂的输出规范：\n\n```python\nfrom outlines.types import either, optional, at_least, integer\n\n# either: 匹配多个选项之一\nchoice = either(\"option_a\", \"option_b\", \"option_c\")\n\n# optional: 可选的元素\nelement = optional(\"prefix:\")\n\n# at_least: 至少重复次数\nrepeated = at_least(integer(), min_times=1)\n\n# integer: 整数类型\nnum = integer()\n```\n\n资料来源：[outlines/types/dsl.py:200-280]()\n\n### Python 类型到 Term 的转换\n\n`python_types_to_terms()` 函数负责将标准 Python 类型转换为 Term 实例：\n\n| Python 类型 | 转换目标 | 示例 |\n|-------------|----------|------|\n| `int` | `integer()` | `int` → 整数约束 |\n| `float` | `float_()` | `float` → 浮点数约束 |\n| `str` | `string()` | `str` → 字符串约束 |\n| `bool` | `literal(True/False)` | `bool` → 布尔约束 |\n| `Literal[\"A\", \"B\"]` | `alternatives(...)` | 枚举值约束 |\n| `Enum` | `alternatives(...)` | 枚举类约束 |\n| `List[T]` | `array(term_from(T))` | 列表约束 |\n| `Dict[K, V]` | `object(...)` | 字典约束 |\n\n```python\ndef python_types_to_terms(py_type: Any) -> Term:\n \"\"\"将 Python 类型递归转换为 Term 实例\"\"\"\n # 处理 Literal 类型\n if is_literal(py_type):\n return alternatives(*get_args(py_type))\n \n # 处理枚举类型\n if is_enum(py_type):\n return alternatives(*[e.value for e in py_type])\n \n # 处理列表类型\n if is_list(py_type):\n element_type = get_args(py_type)[0]\n return array(python_types_to_terms(element_type))\n \n # ... 更多类型处理\n```\n\n资料来源：[outlines/types/dsl.py:300-400]()\n\n## 输出类型（Output Types）\n\n### 内置输出类型\n\nOutlines 支持多种输出类型，可直接作为模型调用的第二个参数：\n\n```python\nfrom typing import Literal\nfrom pydantic import BaseModel\n\n# 简单类型\nresult = model(\"What's 2+2?\", int) # 输出整数\n\n# 字面量类型\nsentiment = model(\"Great product!\", Literal[\"positive\", \"negative\", \"neutral\"])\n\n# Pydantic 模型\nclass User(BaseModel):\n name: str\n age: int\n email: str\n\nuser = model(\"Extract user info\", User)\n```\n\n### JsonSchema 类型\n\n`JsonSchema` 术语允许直接使用 JSON Schema 字符串定义输出结构：\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '''\n{\n \"type\": \"object\",\n \"properties\": {\n \"answer\": {\"type\": \"number\"}\n }\n}\n'''\n\nresult = model(\"What's 2+2?\", JsonSchema(json_schema))\n```\n\n资料来源：[outlines/release_note.md:80-100]()\n\n### CFG（上下文无关文法）\n\nCFG 允许使用 Lark 语法定义自定义文法：\n\n```python\nfrom outlines.types import CFG\n\ngrammar = \"\"\"\nstart: expression\nexpression: term ((ADD | SUB) term)*\nterm: factor ((MUL | DIV) factor)*\nfactor: NUMBER | \"(\" expression \")\"\nADD: \"+\"\nSUB: \"-\"\nMUL: \"*\"\nDIV: \"/\"\nNUMBER: /[0-9]+/\n\"\"\"\n\nresult = model(\"Calculate 2+3*4\", CFG(grammar))\n```\n\n资料来源：[outlines/grammars/json.lark]() 及 [outlines/types/dsl.py]()\n\n## JSON Schema 与 Pydantic 互转\n\n类型系统提供了 JSON Schema 与其他格式的双向转换能力：\n\n### JSON Schema 转 Pydantic\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_pydantic\n\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"age\": {\"type\": \"integer\"}\n }\n}\n\nPydanticModel = json_schema_dict_to_pydantic(schema)\n```\n\n### JSON Schema 转 TypedDict\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_typeddict\n\nTypedDictModel = json_schema_dict_to_typeddict(schema)\n```\n\n### JSON Schema 转 Dataclass\n\n```python\nfrom outlines.types.json_schema_utils import json_schema_dict_to_dataclass\n\nDataClassModel = json_schema_dict_to_dataclass(schema)\n```\n\n资料来源：[outlines/types/dsl.py:60-90]()\n\n## 与生成器的集成\n\n### Generator 类\n\n`Generator` 类封装了模型和输出类型，提供了可复用的生成接口：\n\n```python\nfrom outlines import Generator, from_transformers\n\nmodel = from_transformers(...)\n\n# 创建生成器，输出类型编译一次\ngenerator = Generator(model, MyOutputType)\n\n# 多次复用同一生成器\nresult1 = generator(\"prompt1\")\nresult2 = generator(\"prompt2\")\n```\n\n### 模型直接调用\n\n模型也可以直接调用，类型系统在每次调用时编译：\n\n```python\n# 直接调用方式\nresult = model(\"prompt\", MyOutputType)\n\n# 等价于使用 Generator\ngenerator = Generator(model, MyOutputType)\nresult = generator(\"prompt\")\n```\n\n资料来源：[outlines/models/base.py:100-150]()\n\n## 异常处理\n\n类型系统在遇到无效类型或转换错误时，会抛出标准化的异常：\n\n| 异常类 | 描述 | 源码位置 |\n|--------|------|----------|\n| `OutlinesError` | 基础异常类 | [exceptions.py:30]() |\n| `APIError` | API 相关错误基类 | [exceptions.py:35]() |\n| `ProviderResponseError` | 提供商响应错误 | [exceptions.py:55]() |\n| `GenerationError` | 生成过程中的错误 | [exceptions.py:60]() |\n\n```python\ntry:\n result = model(\"prompt\", InvalidType)\nexcept OutlinesError as e:\n print(f\"类型系统错误: {e}\")\n```\n\n资料来源：[outlines/exceptions.py:20-70]()\n\n## 完整使用示例\n\n```python\nimport outlines\nfrom typing import Literal, List\nfrom pydantic import BaseModel\nfrom enum import Enum\n\n# 定义枚举类型\nclass Category(str, Enum):\n TECH = \"technology\"\n FOOD = \"food\"\n TRAVEL = \"travel\"\n\n# 定义 Pydantic 模型\nclass Article(BaseModel):\n title: str\n summary: str\n category: Category\n tags: List[str]\n published: bool\n\n# 初始化模型\nmodel = outlines.from_transformers(...)\n\n# 提取结构化信息\narticle = model(\n \"Write about AI advancements in healthcare\",\n Article\n)\n\n# 使用字面量类型快速分类\nsentiment = model(\n \"The new iPhone is amazing!\",\n Literal[\"positive\", \"negative\", \"neutral\"]\n)\n```\n\n## 模块导出\n\n`outlines.types` 模块的公共 API：\n\n```python\n# outlines/types/__init__.py 导出\n__all__ = [\n \"Term\", # 基础术语类\n \"JsonSchema\", # JSON Schema 术语\n \"CFG\", # 上下文无关文法\n \"Regex\", # 正则表达式术语\n \"String\", # 字符串术语\n \"integer\", # 整数术语工厂函数\n \"float_\", # 浮点数术语工厂函数\n \"string\", # 字符串术语工厂函数\n \"either\", # 组合函数：或\n \"optional\", # 组合函数：可选\n \"at_least\", # 组合函数：至少\n \"alternatives\", # 组合函数：多选一\n \"array\", # 组合函数：数组\n \"object\", # 组合函数：对象\n]\n```\n\n资料来源：[outlines/types/__init__.py]()\n\n---\n\n\n\n## 模型提供者\n\n### 相关页面\n\n相关主题：[生成器系统](#page-generator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/models/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/__init__.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/models/transformers.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/transformers.py)\n- [outlines/models/openai.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/openai.py)\n- [outlines/models/vllm.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/vllm.py)\n- [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n \n\n# 模型提供者\n\n## 概述\n\n模型提供者（Model Providers）是 Outlines 框架中负责与不同大语言模型后端进行交互的核心抽象层。Outlines 实现了统一的接口，使得用户可以使用相同的代码调用方式访问来自不同提供商的模型，包括本地 transformers 模型、OpenAI、Anthropic、vLLM 等。\n\nOutlines 的核心设计理念是\"**任何模型都适用**\"——相同的代码可以在不同的模型提供商之间切换而无需修改业务逻辑。这种设计通过模型提供者架构实现，将模型交互的细节封装在统一的接口之后。资料来源：[README.md:1-10]()\n\n## 架构设计\n\n### 分层架构\n\n```\n用户 API (outlines.models)\n ↓\n生成器类 (SteerableGenerator, BlackBoxGenerator)\n ↓\n类型系统 (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM 编译 (outlines-core: regex → FSM via interegular)\n ↓\nGuide 系统 (processors/guide.py: FSM 状态管理)\n ↓\nLogits 处理 (processors/structured.py: token 掩码)\n ↓\n模型提供者 (transformers, OpenAI, 等)\n```\n\n### 模型类层次结构\n\nOutlines 中的模型类分为两大类别：\n\n| 类别 | 描述 | 控制层级 | 支持的提供者 |\n|------|------|----------|--------------|\n| **SteerableModel** | 可操纵模型 | 完全控制 logits | transformers, llama.cpp, vLLM |\n| **BlackBoxModel** | 黑盒模型 | 通过 API 调用 | OpenAI, Anthropic, Google Gemini |\n\n资料来源：[llm.txt:1-25]()\n\n### 基类设计\n\n所有模型提供者都继承自 `BaseModel` 类，该类定义了共享的 `__call__`、`batch` 和 `stream` 方法。模型类必须定义 `type_adapter` 属性（类型为 `ModelTypeAdapter`），用于格式化输入和输出类型。\n\n```python\n# outlines/models/base.py\nclass BaseModel(ABC):\n \"\"\"所有异步模型的基类\"\"\"\n type_adapter: ModelTypeAdapter\n tensor_library_name: str\n\n async def __call__(\n self,\n model_input: Any,\n output_type: Optional[Any] = None,\n backend: Optional[str] = None,\n **inference_kwargs: Any\n ) -> Any:\n \"\"\"直接调用模型\"\"\"\n```\n\n资料来源：[outlines/models/base.py:1-50]()\n\n## 支持的模型提供者\n\n### 本地模型提供者\n\n#### Transformers\n\n`Transformers` 提供者允许使用 Hugging Face Transformers 库加载的本地模型。这是 Outlines 最基础的提供者，通过完全控制 logits 实现结构化生成。\n\n```python\nimport outlines\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"What's 2 + 2?\", int)\n```\n\n资料来源：[README.md:40-55]()\n\n#### vLLM\n\n`vLLM` 提供者支持通过 vLLM 推理引擎运行模型，提供高效的批量推理能力。\n\n```python\nfrom outlines import from_vllm\n\nmodel = from_vllm(\n \"microsoft/Phi-3-mini-4k-instruct\"\n)\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n```\n\n资料来源：[outlines/release_note.md:80-90]()\n\n#### Llama.cpp\n\n支持通过 llama.cpp 进行 CPU 或 GPU 推理的模型。\n\n### API 模型提供者\n\n#### OpenAI\n\n`OpenAI` 提供者封装了 OpenAI API，支持 GPT-4、GPT-3.5-Turbo 等模型。\n\n#### Anthropic\n\n支持 Claude 系列模型的调用。\n\n#### Google Gemini\n\n`Gemini` 提供者封装了 Google AI 的 Gemini 模型：\n\n```python\nfrom outlines import from_gemini\nfrom google.genai import Client\n\nmodel = from_gemini(Client(api_key=\"your-api-key\"))\n```\n\n资料来源：[outlines/models/gemini.py:1-30]()\n\n### 异步推理端点\n\nOutlines 还支持异步推理端点，特别适用于生产环境：\n\n| 提供者 | 类名 | 描述 |\n|--------|------|------|\n| SGLang | `AsyncSGLang` | 异步 SGLang 推理服务器 |\n| TGI | `AsyncTGI` | 异步 Text Generation Inference 服务器 |\n| vLLM | `AsyncVLLM` | 异步 vLLM 推理服务器 |\n\n```python\nfrom outlines import from_tgi\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n资料来源：[outlines/release_note.md:60-70]()\n\n## 核心接口\n\n### 模型调用方法\n\n所有模型提供者都实现了以下核心方法：\n\n#### `__call__` - 单次生成\n\n```python\nresult = model(\"Your prompt here\", output_type)\n```\n\n#### `stream` - 流式生成\n\n```python\nfor chunk in model.stream(\"Your prompt here\", output_type):\n print(chunk)\n```\n\n#### `batch` - 批量生成\n\n```python\nresults = model.batch(\n [\"prompt1\", \"prompt2\", \"prompt3\"],\n output_type\n)\n```\n\n资料来源：[outlines/models/base.py:50-120]()\n\n### 推理参数\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `model_input` | Any | 输入提示或提示列表 |\n| `output_type` | Optional[Any] | 输出类型约束 |\n| `backend` | Optional[str] | 后端名称（用于可操纵模型） |\n| `**inference_kwargs` | Any | 额外推理参数（如 max_tokens, temperature） |\n\n## 使用模式\n\n### 模式一：直接模型调用\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 直接调用\nresult = model(\"What's 2 + 2?\", int) # 返回 4\n```\n\n### 模式二：使用生成器\n\n生成器模式允许重用编译后的输出类型，提高批量调用效率：\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 创建生成器，输出类型只编译一次\ngenerator = Generator(model, int)\n\n# 多次使用同一生成器\nresult1 = generator(\"What's 2 + 2?\")\nresult2 = generator(\"What's 5 + 3?\")\n```\n\n资料来源：[outlines/release_note.md:90-105]()\n\n### 模式三：Pydantic 模型输出\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\nreview = model(\"生成一个产品评价\", ProductReview)\n```\n\n## LoRA 支持\n\n### vLLM LoRA 加载\n\nvLLM 模型支持通过 `lora_request` 参数加载 LoRA 适配器：\n\n```python\nfrom outlines import from_vllm\nfrom vllm import LLM\nfrom vllm.lora.request import LoRARequest\n\nmodel = from_vllm(LLM(\"microsoft/Phi-3-mini-4k-instruct\"))\nlora_request = LoRARequest(\"my_lora\", 1, \"path/to/lora/file\")\nresult = model(\"Write a short story\", str, lora_request=lora_request)\n```\n\n资料来源：[outlines/release_note.md:110-125]()\n\n## 版本变更说明\n\n### v1.0 主要变更\n\n在 Outlines v1.0 中，模型接口经历了重大修改：\n\n| 变更项 | 旧版本 | 新版本 |\n|--------|--------|--------|\n| 调用方式 | 先创建生成器再调用 | 直接 `model(prompt, output_type)` |\n| 流式接口 | 需创建特定生成器 | 所有模型都有 `stream` 方法 |\n| LoRA 加载 | `model.load_lora()` | 通过参数传递 `lora_request` |\n\n### 已弃用的提供者\n\n- **Exllamav2**: 由于接口不完全兼容，已从 Outlines 中移除\n\n资料来源：[outlines/release_note.md:30-50]()\n\n## 最佳实践\n\n### 1. 选择合适的提供者\n\n```mermaid\ngraph TD\n A[开始] --> B{需求场景}\n B -->|需要完全控制| C[SteerableModel]\n B -->|使用云端API| D[BlackBoxModel]\n C -->|HuggingFace模型| E[Transformers]\n C -->|高吞吐需求| F[vLLM]\n D -->|OpenAI生态| G[OpenAI]\n D -->|Anthropic生态| H[Anthropic]\n```\n\n### 2. 性能优化建议\n\n- **批量处理**：使用 `batch` 方法进行批量推理，减少 API 调用开销\n- **生成器复用**：频繁调用同一输出类型时使用 `Generator` 避免重复编译\n- **本地缓存**：transformers 模型首次加载后会被缓存\n\n### 3. 生产环境部署\n\n对于生产环境，推荐使用异步推理端点：\n\n```python\n# 推荐的生产配置\nasync_model = outlines.from_vllm(\n AsyncInferenceClient(\"http://your-vllm-server:8000\")\n)\n```\n\n## 相关模块\n\n- [Generator](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py) - 生成器核心类\n- [Type System](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py) - 类型系统与约束编译\n- [FSM Compilation](https://github.com/dottxt-ai/outlines/blob/main/outlines_core) - 有限状态机编译\n\n---\n\n\n\n## 生成器系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [模型提供者](#page-model-providers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\n- [outlines/inputs.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/inputs.py)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/__init__.py)\n \n\n# 生成器系统\n\n## 概述\n\n生成器系统（Generator System）是 Outlines 框架的核心抽象层，负责将结构化输出类型与语言模型解耦，实现可复用、可组合的生成管线。生成器接收模型实例和输出类型作为构造参数，返回一个可迭代的生成器对象，用户可反复使用该对象进行结构化文本生成而无需每次重新指定输出类型。\n\n生成器系统的核心价值在于**延迟编译和复用机制**：输出类型的有限状态机（FSM）仅在首次使用时编译一次，后续调用直接复用已编译的状态机，显著提升高频调用场景的性能。资料来源：[release_note.md]()\n\n## 架构设计\n\n### 层级结构\n\n```\n用户代码 (User Code)\n ↓\n┌─────────────────────────────────────┐\n│ Generator (生成器) │\n│ - 持有模型引用与输出类型 │\n│ - 管理 FSM 编译与缓存 │\n│ - 提供同步/异步生成接口 │\n└─────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────┐\n│ Model (模型适配器) │\n│ - SteerableModel / BlackBoxModel │\n│ - logits 处理 / API 调用封装 │\n└─────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────┐\n│ 输出类型系统 (Output Types) │\n│ - Pydantic → JsonSchema → Regex │\n│ - FSM 编译 (outlines-core) │\n└─────────────────────────────────────┘\n```\n\n### 关键设计决策\n\n| 决策 | 说明 |\n|------|------|\n| **惰性编译** | FSM 在首次调用时编译并持久化缓存 |\n| **统一接口** | 同步/异步、流式/批量使用相同 API |\n| **模型无关** | 支持本地模型(transformers)和 API 模型(OpenAI) |\n| **类型驱动** | Python 类型注解是主要的约束声明方式 |\n\n资料来源：[llm.txt]()\n\n## 核心组件\n\n### Generator 类\n\n`Generator` 是生成器系统的核心类，封装了模型实例、输出类型和编译后的 FSM。\n\n**构造函数签名：**\n\n```python\nGenerator(model, output_type, backend=None)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `Model` | 已初始化的 Outlines 模型实例 |\n| `output_type` | `type` | Python 类型或类型别名（int, Literal, BaseModel 等） |\n| `backend` | `str \\| None` | 后端名称，仅用于可转向模型(steerable models) |\n\n资料来源：[outlines/generator.py]()\n\n### 同步生成方法\n\n```python\n# 单次生成\nresult = generator(\"prompt\", **inference_kwargs)\n\n# 批量生成\nresults = generator.batch([\"prompt1\", \"prompt2\"], **inference_kwargs)\n```\n\n| 方法 | 参数 | 返回值 |\n|------|------|--------|\n| `__call__` | `prompt`, `**inference_kwargs` | `Any`（单条生成结果） |\n| `batch` | `List[prompt]`, `**inference_kwargs` | `List[Any]`（批量结果列表） |\n\n资料来源：[outlines/models/base.py:1-100]()\n\n### 异步生成方法\n\n```python\n# 异步单次生成\nresult = await generator(\"prompt\", **inference_kwargs)\n\n# 异步批量生成\nresults = await generator.batch([\"prompt1\", \"prompt2\"], **inference_kwargs)\n\n# 流式生成\nasync for chunk in generator.stream(\"prompt\", **inference_kwargs):\n print(chunk)\n```\n\n| 方法 | 参数 | 返回值 |\n|------|------|--------|\n| `__call__` (async) | `prompt`, `**inference_kwargs` | `Coroutine[Any]` |\n| `batch` (async) | `List[prompt]`, `**inference_kwargs` | `Coroutine[List[Any]]` |\n| `stream` (async) | `prompt`, `**inference_kwargs` | `AsyncIterator[Any]` |\n\n资料来源：[outlines/models/base.py:100-200]()\n\n## 输入处理系统\n\n`outlines/inputs.py` 负责处理各种格式的模型输入，将其标准化为统一的内部表示。\n\n### 输入类型支持\n\n| 输入类型 | 说明 | 示例 |\n|----------|------|------|\n| 字符串 | 纯文本 prompt | `\"今天天气如何？\"` |\n| 消息列表 | 对话格式 | `[{\"role\": \"user\", \"content\": \"...\"}]` |\n| 模板对象 | Jinja 模板渲染后的字符串 | `template(content=\"...\")` |\n\n资料来源：[outlines/inputs.py]()\n\n## 异常处理体系\n\nOutlines 定义了完整的异常层次结构，所有公共异常继承自 `OutlinesError` → `APIError` → `Exception`。\n\n### 异常类层次\n\n```\nOutlinesError\n└── APIError (provider: str, status_code: int, request_id: str)\n ├── AuthenticationError (401)\n ├── PermissionDeniedError (403)\n ├── NotFoundError (404)\n ├── BadRequestError (400)\n ├── RateLimitError (429)\n ├── ServerError (5xx)\n ├── APITimeoutError\n └── APIConnectionError\n└── ProviderResponseError\n└── GenerationError\n```\n\n### 异常属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `provider` | `str \\| None` | 提供商名称（如 `\"openai\"`） |\n| `status_code` | `int \\| None` | HTTP 状态码 |\n| `request_id` | `str \\| None` | 请求追踪 ID |\n| `retryable` | `bool` | 是否可重试 |\n| `hint` | `str` | 用户友好的建议信息 |\n\n资料来源：[outlines/exceptions.py]()\n\n## 使用模式\n\n### 模式一：直接模型调用 vs 生成器调用\n\n**直接调用模式（v1 新增）：**\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n```\n\n**生成器模式（可复用）：**\n\n```python\nfrom pydantic import BaseModel\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ngenerator = Generator(model, Character)\n# 多次调用无需重新指定输出类型\nresponse1 = generator(\"Create a male character.\")\nresponse2 = generator(\"Create a female character.\")\n```\n\n资料来源：[release_note.md]()\n\n### 模式二：流式生成\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ngenerator = Generator(model, str)\n\n# 同步流式（需调用 stream 方法）\nfor chunk in generator.stream(\"Write a story about a cat\"):\n print(chunk, end=\"\", flush=True)\n```\n\n### 模式三：异步批量处理\n\n```python\nimport asyncio\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nasync def main():\n model = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n )\n \n generator = Generator(model, str)\n prompts = [f\"Analyze sentiment: {text}\" for text in texts]\n results = await generator.batch(prompts)\n return results\n\nasyncio.run(main())\n```\n\n## API 模型生成器\n\n对于 API 类模型（如 OpenAI、Anthropic），生成器通过 `BlackBoxModel` 封装，利用提供商的结构化输出支持。\n\n### OpenAI 示例\n\n```python\nfrom openai import OpenAI\nfrom pydantic import BaseModel\nfrom outlines import Generator, from_openai\n\nclass Character(BaseModel):\n name: str\n age: int\n\nclient = OpenAI()\nmodel = from_openai(client)\ngenerator = Generator(model, Character)\n\nresult = generator(\"Create a character named Alice, age 25\")\n```\n\n资料来源：[release_note.md]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[创建 Generator] --> B{输出类型已编译?}\n B -->|否| C[调用 FSM 编译]\n C --> D[缓存 FSM]\n B -->|是| E[复用缓存 FSM]\n E --> F[准备 Prompt]\n D --> F\n F --> G{模型类型}\n G -->|Steerable| H[应用 Logits Processor]\n G -->|BlackBox| I[调用 API 结构化输出]\n H --> J[采样下一个 Token]\n I --> K[解析结构化响应]\n J --> L{是否结束?}\n L -->|否| J\n L -->|是| M[返回结果]\n K --> M\n```\n\n## 版本迁移指南\n\n### v0 到 v1 的变化\n\n| v0 方式 | v1 方式 |\n|---------|---------|\n| `generate.json(model, Character)` | `Generator(model, Character)` |\n| `models.openai(\"gpt-4o\")` | `from_openai(OpenAI())` |\n| `generator(prompt)` | `generator(prompt)` |\n| `model.load_lora(...)` | `lora_request=LoRARequest(...)` |\n\n资料来源：[release_note.md]()\n\n## 最佳实践\n\n1. **重复使用生成器**：创建生成器后应复用，避免重复编译 FSM\n2. **选择合适的输出类型**：简单类型用 `Literal`，复杂结构用 Pydantic\n3. **处理异常**：使用 `try/except OutlinesError` 捕获结构化错误\n4. **流式输出**：长文本生成使用流式接口改善用户体验\n5. **批量处理**：多 prompt 场景使用 `batch` 方法提高吞吐量\n\n## 相关模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| 生成器核心 | `outlines/generator.py` | Generator 类实现 |\n| 输入处理 | `outlines/inputs.py` | Prompt 标准化 |\n| 异常定义 | `outlines/exceptions.py` | 错误类型定义 |\n| 模型基类 | `outlines/models/base.py` | 模型抽象接口 |\n| 模型实现 | `outlines/models/*.py` | 各提供商适配器 |\n\n---\n\n\n\n## 后端系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/backends/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/base.py)\n- [outlines/backends/outlines_core.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/outlines_core.py)\n- [outlines/backends/xgrammar.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/xgrammar.py)\n- [outlines/backends/llguidance.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/llguidance.py)\n \n\n# 后端系统\n\n## 概述\n\nOutlines 的后端系统是负责将结构化输出约束（如正则表达式、JSON Schema、Pydantic 模型等）转换为模型推理过程中可执行的日志处理器（Logits Processor）的核心模块。该系统通过抽象化的后端接口，支持多种底层约束编译引擎，使用户能够在不同的生成场景中灵活选择最合适的约束实现方式。\n\n后端系统在整个 Outlines 架构中扮演着关键角色，它位于类型系统（Type System）与模型推理层之间，负责将高级约束描述编译为低级的有限状态机（FSM）或指导序列（Guide），并生成对应的日志处理器来控制 token 的生成过程。\n\n资料来源：[llm.txt]()\n\n## 架构设计\n\n### 层级架构\n\n```\n用户 API (outlines.models)\n ↓\n生成器类 (SteerableGenerator, BlackBoxGenerator)\n ↓\n类型系统 (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM 编译层 (outlines-core: regex → FSM via interegular)\n ↓\n后端系统 (backends/: 抽象接口与多种实现)\n ↓\n日志处理 (processors/structured.py: token masking)\n ↓\n模型提供者 (transformers, OpenAI, etc.)\n```\n\n### 后端抽象设计\n\nOutlines 采用后端抽象模式，为不同的约束编译引擎提供统一的接口。所有的后端实现都继承自基类 `Backend`，该基类定义了后端必须实现的核心方法，包括约束编译、状态管理和日志处理等。\n\n```mermaid\ngraph TD\n A[用户调用 Generator] --> B[Backend 抽象层]\n B --> C[OutlinesCore 后端]\n B --> D[XGrammar 后端]\n B --> E[LLGuidance 后端]\n C --> F[interegular 编译 FSM]\n D --> G[XGrammar 库]\n E --> H[llguidance 库]\n```\n\n资料来源：[outlines/backends/base.py]()\n\n## 核心组件\n\n### 后端基类 (Backend)\n\n所有具体后端实现都需要继承 `Backend` 基类，该类定义了统一的后端接口：\n\n| 方法名 | 功能描述 | 返回类型 |\n|--------|----------|----------|\n| `__init__` | 初始化后端实例 | None |\n| `name` | 返回后端标识名称 | str |\n| `__call__` | 执行约束编译 | Any |\n| `fsm_graph` | 获取 FSM 图结构 | FSMGraph |\n| `get一方文和_状态` | 获取当前 FSM 状态 | int |\n| `reset` | 重置 FSM 状态 | None |\n\n资料来源：[outlines/backends/base.py]()\n\n### OutlinesCore 后端\n\n`OutlinesCore` 是 Outlines 的默认后端实现，基于 `interegular` 库将正则表达式转换为有限状态机。该后端利用 `outlines-core` 包的底层能力，实现高效的 FSM 编译和状态管理。\n\n**核心特性：**\n- 使用 `interegular` 库进行正则表达式解析和 FSM 转换\n- 支持缓存已编译的 FSM 以提高性能\n- 兼容所有基于 FSM 的约束类型\n\n**工作流程：**\n```mermaid\ngraph LR\n A[正则表达式/约束] --> B[interegular 解析]\n B --> C[FSM 构建]\n C --> D[状态缓存]\n D --> E[Logits Processor]\n```\n\n资料来源：[outlines/backends/outlines_core.py]()\n\n### XGrammar 后端\n\n`XGrammar` 后端是由 MLC-LLM 社区开发的高性能约束编译引擎，专为结构化生成设计。该后端提供了比默认实现更快的约束匹配速度，特别适合对延迟敏感的应用场景。\n\n**主要优势：**\n- 高度优化的状态转移算法\n- 支持字节级（byte-level）约束\n- 更低的内存占用\n\n资料来源：[outlines/backends/xgrammar.py]()\n\n### LLGuidance 后端\n\n`LLGuidance` 后端提供了另一种结构化生成的实现方式，支持更复杂的约束语法和模式匹配能力。该后端适合需要高级约束特性的高级用户。\n\n**支持的功能：**\n- 复杂的正则表达式模式\n- 自定义终止条件\n- 多模态约束支持\n\n资料来源：[outlines/backends/llguidance.py]()\n\n## 后端注册与选择机制\n\n### 后端初始化\n\nOutlines 通过后端注册机制管理可用的后端实现。用户可以在创建生成器时指定使用哪个后端：\n\n```python\nfrom outlines import Generator, from_transformers\n\nmodel = from_transformers(\"microsoft/Phi-3-mini-4k-instruct\")\n\n# 使用默认后端\ngenerator = Generator(model, MySchema)\n\n# 指定特定后端\ngenerator = Generator(model, MySchema, backend=\"xgrammar\")\n```\n\n资料来源：[outlines/backends/__init__.py]()\n\n### 后端自动选择\n\n当用户未指定后端时，Outlines 会根据以下优先级自动选择可用的后端：\n\n1. **OutlinesCore**（默认）- 最广泛的兼容性\n2. **XGrammar** - 高性能场景\n3. **LLGuidance** - 高级约束需求\n\n## FSM 状态管理\n\n### 状态转换机制\n\nFSM（有限状态机）是约束编译的核心数据结构。每个 FSM 由多个状态节点和状态转移边组成，模型在生成每个 token 时都会根据当前状态确定合法的下一个 token 集合。\n\n```mermaid\ngraph TD\n S0[状态 0: 初始状态] -->|token A| S1[状态 1]\n S0 -->|token B| S2[状态 2]\n S1 -->|token C| S1\n S1 -->|token D| S3[状态 3: 终止]\n S2 -->|token E| S3\n S3 -->|\"[END]\"| S4[完成]\n```\n\n### 状态缓存\n\nOutlines 支持 FSM 缓存机制，避免对相同约束重复编译。缓存键由约束的哈希值和版本号组成，确保缓存的一致性和有效性。\n\n资料来源：[outlines/backends/outlines_core.py]()\n\n## 与生成器系统的集成\n\n### SteerableGenerator\n\n`SteerableGenerator` 是用于可控模型（如 Transformers、llama.cpp）的生成器类。它直接调用后端系统来创建日志处理器，在推理过程中实时过滤不合法的 token。\n\n```python\ngenerator = Generator(model, output_type, backend)\nresult = generator(\"提示词\")\n```\n\n### BlackBoxGenerator\n\n`BlackBoxGenerator` 用于黑盒 API 模型（如 OpenAI、Anthropic）。这类模型不支持直接的日志处理，因此后端系统会生成符合模型原生结构化输出格式的提示。\n\n资料来源：[outlines/models/base.py]()\n\n## 配置选项\n\n### 后端级配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `backend` | str | \"outlines_core\" | 指定使用的后端引擎 |\n| `cache_dir` | Path | None | FSM 缓存目录 |\n| `enable_cache` | bool | True | 是否启用 FSM 缓存 |\n| `fsm_options` | dict | {} | 后端特定配置项 |\n\n### 运行时配置\n\n在调用生成器时可以传递推理参数，这些参数会与后端的约束处理机制协同工作：\n\n```python\nresult = model(\n \"提示词\",\n temperature=0.7,\n max_tokens=100,\n num_beams=2\n)\n```\n\n## 扩展后端\n\n### 自定义后端接口\n\n要实现自定义后端，需要继承 `Backend` 基类并实现以下方法：\n\n1. `__init__(self, ...)`: 初始化后端\n2. `name(self) -> str`: 返回后端名称\n3. `__call__(self, ...) -> LogitsProcessor`: 创建日志处理器\n4. `fsm_graph(self) -> FSMGraph`: 返回 FSM 图结构\n\n### 注册自定义后端\n\n自定义后端可以通过修改 `backends/__init__.py` 来注册到 Outlines 系统中。\n\n资料来源：[outlines/backends/__init__.py]()\n\n## 性能考量\n\n### 后端性能对比\n\n| 后端 | 编译速度 | 推理速度 | 内存占用 | 兼容性 |\n|------|----------|----------|----------|--------|\n| OutlinesCore | 中等 | 中等 | 中等 | 高 |\n| XGrammar | 快 | 快 | 低 | 中 |\n| LLGuidance | 慢 | 快 | 高 | 中 |\n\n### 优化建议\n\n- **重复约束**：启用 FSM 缓存以避免重复编译\n- **高频调用**：考虑使用 XGrammar 后端以获得更低的延迟\n- **复杂约束**：使用 LLGuidance 后端的扩展语法支持\n\n## 错误处理\n\n### 后端相关异常\n\n后端系统可能抛出的异常类型包括：\n\n| 异常类型 | 触发场景 | 处理建议 |\n|----------|----------|----------|\n| `BackendNotAvailableError` | 请求的后端不可用 | 检查后端安装或使用备选后端 |\n| `CompilationError` | 约束编译失败 | 检查约束语法是否正确 |\n| `FSMCacheError` | 缓存读写失败 | 检查缓存目录权限 |\n\n资料来源：[outlines/exceptions.py]()\n\n## 相关文档\n\n- [核心特性文档](https://dottxt-ai.github.io/outlines/latest/features/core/generator)\n- [模型集成指南](https://dottxt-ai.github.io/outlines/latest/features/models)\n- [输出类型参考](https://dottxt-ai.github.io/outlines/latest/features/core/ouput_types)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：dottxt-ai/outlines\n\n摘要：发现 29 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] Streaming structured generation with partial validation。\n\n## 1. 安装坑 · 来源证据：[Feature] Streaming structured generation with partial validation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 维护坑 · 来源证据：Add more custom types\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：Add function calling and MCP support\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Feature Request] Add streaming support for structured generation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- 对用户的影响：Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 7. 安装坑 · 失败模式：installation: Outlines v1.2.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.6\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n\n## 8. 安装坑 · 失败模式：installation: Outlines v1.2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.8\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n\n## 9. 安装坑 · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 失败模式：migration: Outlines v1.2.10\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: Outlines v1.2.10\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.10\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10\n\n## 12. 维护坑 · 失败模式：migration: Outlines v1.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: Outlines v1.3.0\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.3.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0\n\n## 13. 维护坑 · 来源证据：Complex structure makes output empty\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：Incompatibility with vllm==0.19 because of some api changes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Incompatibility with vllm==0.19 because of some api changes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45101a3eaffb4eda98b4d597dd5aca64 | https://github.com/dottxt-ai/outlines/issues/1854 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_85cb7bc56eb64613b9ec65e51dea90e9 | https://github.com/dottxt-ai/outlines/issues/1847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 能力坑 · 失败模式：capability: Add function calling and MCP support\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Add function calling and MCP support\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Add function calling and MCP support\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add function calling and MCP support. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_dfb58c522eebbd15e72f7bfbfc936335 | https://github.com/dottxt-ai/outlines/issues/1626 | Add function calling and MCP support\n\n## 20. 能力坑 · 失败模式：capability: Add more custom types\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Add more custom types\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Add more custom types\n- 建议检查：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.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_8ba5f20b34d61b76171e5fdc02fffff8 | https://github.com/dottxt-ai/outlines/issues/1303 | Add more custom types\n\n## 21. 能力坑 · 失败模式：capability: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 对用户的影响：Developers may hit a documented source-backed failure mode: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 22. 能力坑 · 失败模式：capability: [Feature] Streaming structured generation with partial validation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: [Feature] Streaming structured generation with partial validation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature] Streaming structured generation with partial validation\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Streaming structured generation with partial validation. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0990edf56e70825cebd4d6337f2e9ec7 | https://github.com/dottxt-ai/outlines/issues/1856 | [Feature] Streaming structured generation with partial validation\n\n## 23. 能力坑 · 失败模式：capability: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_7477c33ba4e3aefcd5a822e817746461 | https://github.com/dottxt-ai/outlines/issues/1859 | 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n## 24. 能力坑 · 失败模式：conceptual: Complex structure makes output empty\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: Complex structure makes output empty\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Complex structure makes output empty\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_adb9b1e93b18abc454b9ec796b30af1a | https://github.com/dottxt-ai/outlines/issues/1861 | Complex structure makes output empty\n\n## 25. 运行坑 · 失败模式：performance: [Feature Request] Add streaming support for structured generation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this performance risk before relying on the project: [Feature Request] Add streaming support for structured generation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Add streaming support for structured generation\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f9e262951793c35ca4f0f973546df68f | https://github.com/dottxt-ai/outlines/issues/1842 | [Feature Request] Add streaming support for structured generation\n\n## 26. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | issue_or_pr_quality=unknown\n\n## 27. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | release_recency=unknown\n\n## 28. 维护坑 · 失败模式：maintenance: Outlines v1.2.12\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.12\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.12\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.12. Context: Observed when using docker\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_654aac443ea5eec7b12b4b1cbe602de9 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.13 | Outlines v1.2.12\n\n## 29. 维护坑 · 失败模式：maintenance: Outlines v1.2.9\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.9\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.9\n- 建议检查：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.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e26ccdb4b7c8d266e55856497effd5ae | https://github.com/dottxt-ai/outlines/releases/tag/1.2.9 | Outlines v1.2.9\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：dottxt-ai/outlines\n\n摘要：发现 29 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] Streaming structured generation with partial validation。\n\n## 1. 安装坑 · 来源证据：[Feature] Streaming structured generation with partial validation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 维护坑 · 来源证据：Add more custom types\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：Add function calling and MCP support\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Feature Request] Add streaming support for structured generation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- 对用户的影响：Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 7. 安装坑 · 失败模式：installation: Outlines v1.2.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.6\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n\n## 8. 安装坑 · 失败模式：installation: Outlines v1.2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.8\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n\n## 9. 安装坑 · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 失败模式：migration: Outlines v1.2.10\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: Outlines v1.2.10\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.10\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10\n\n## 12. 维护坑 · 失败模式：migration: Outlines v1.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: Outlines v1.3.0\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.3.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0\n\n## 13. 维护坑 · 来源证据：Complex structure makes output empty\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：Incompatibility with vllm==0.19 because of some api changes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Incompatibility with vllm==0.19 because of some api changes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45101a3eaffb4eda98b4d597dd5aca64 | https://github.com/dottxt-ai/outlines/issues/1854 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_85cb7bc56eb64613b9ec65e51dea90e9 | https://github.com/dottxt-ai/outlines/issues/1847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 能力坑 · 失败模式：capability: Add function calling and MCP support\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Add function calling and MCP support\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Add function calling and MCP support\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add function calling and MCP support. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_dfb58c522eebbd15e72f7bfbfc936335 | https://github.com/dottxt-ai/outlines/issues/1626 | Add function calling and MCP support\n\n## 20. 能力坑 · 失败模式：capability: Add more custom types\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: Add more custom types\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Add more custom types\n- 建议检查：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.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_8ba5f20b34d61b76171e5fdc02fffff8 | https://github.com/dottxt-ai/outlines/issues/1303 | Add more custom types\n\n## 21. 能力坑 · 失败模式：capability: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 对用户的影响：Developers may hit a documented source-backed failure mode: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 22. 能力坑 · 失败模式：capability: [Feature] Streaming structured generation with partial validation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: [Feature] Streaming structured generation with partial validation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature] Streaming structured generation with partial validation\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Streaming structured generation with partial validation. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0990edf56e70825cebd4d6337f2e9ec7 | https://github.com/dottxt-ai/outlines/issues/1856 | [Feature] Streaming structured generation with partial validation\n\n## 23. 能力坑 · 失败模式：capability: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this capability risk before relying on the project: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation. Context: Observed when using python\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_7477c33ba4e3aefcd5a822e817746461 | https://github.com/dottxt-ai/outlines/issues/1859 | 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n## 24. 能力坑 · 失败模式：conceptual: Complex structure makes output empty\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: Complex structure makes output empty\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Complex structure makes output empty\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_adb9b1e93b18abc454b9ec796b30af1a | https://github.com/dottxt-ai/outlines/issues/1861 | Complex structure makes output empty\n\n## 25. 运行坑 · 失败模式：performance: [Feature Request] Add streaming support for structured generation\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this performance risk before relying on the project: [Feature Request] Add streaming support for structured generation\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Add streaming support for structured generation\n- 建议检查：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\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f9e262951793c35ca4f0f973546df68f | https://github.com/dottxt-ai/outlines/issues/1842 | [Feature Request] Add streaming support for structured generation\n\n## 26. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | issue_or_pr_quality=unknown\n\n## 27. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | release_recency=unknown\n\n## 28. 维护坑 · 失败模式：maintenance: Outlines v1.2.12\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.12\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.12\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.12. Context: Observed when using docker\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_654aac443ea5eec7b12b4b1cbe602de9 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.13 | Outlines v1.2.12\n\n## 29. 维护坑 · 失败模式：maintenance: Outlines v1.2.9\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: Outlines v1.2.9\n- 对用户的影响：Upgrade or migration may change expected behavior: Outlines v1.2.9\n- 建议检查：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.\n- 防护动作: State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e26ccdb4b7c8d266e55856497effd5ae | https://github.com/dottxt-ai/outlines/releases/tag/1.2.9 | Outlines v1.2.9\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# outlines - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 outlines 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Structured Outputs 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Outlines 简介。围绕“Outlines 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Outlines 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Outlines 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-core-concepts：Step 5 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/dottxt-ai/outlines\n- https://github.com/dottxt-ai/outlines#readme\n- README.md\n- outlines/release_note.md\n- pyproject.toml\n- environment.yml\n- examples/dating_profile.py\n- examples/react.py\n- outlines/generator.py\n- outlines/backends/__init__.py\n- outlines/processors/__init__.py\n- llm.txt\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 outlines 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：dottxt-ai/outlines\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install outlines\n```\n\n来源：https://github.com/dottxt-ai/outlines#readme\n\n## 来源\n\n- repo: https://github.com/dottxt-ai/outlines\n- docs: https://github.com/dottxt-ai/outlines#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_12464c5413314f709980a9b98f4740c4"
}