Outlines 接入 Dottxt APIJSON Schema 结构化输出的云端模型集成指南【免费下载链接】outlinesStructured Outputs项目地址: https://gitcode.com/GitHub_Trending/ou/outlinesOutlines 通过from_dottxt加载函数将 Dottxt 云端 API 封装为统一的模型接口让开发者无需关心底层传输协议即可获得 JSON Schema 约束的结构化生成能力。本文基于 docs/features/models/dottxt.md 展开结合 src/outlines/models/dottxt.py 的源码实现与 tests/models/test_dottxt.py 等测试用例完整讲解安装配置、同步/异步模型初始化、约束生成调用方式、推理参数覆盖以及错误类型归一化与能力边界等实战细节。读完本文你将掌握在 Outlines 项目中接入 Dottxt 云模型、用 Pydantic 模型约束输出并处理异常的标准姿势。环境准备安装与 API Key 配置Dottxt 是 Outlines 的可选后端需要单独安装其 Python SDK。在 pyproject.toml 中dottxt被声明为可选依赖组dottxt [dottxt]同时测试依赖要求dottxt0.2.0。安装命令如下pip install outlines[dottxt]安装完成后你还需要一个 Dottxt API Key。获取方式请参考 Outlines 官方文档在dottxt.md中通过官方申请表单入口获取。拿到 Key 后有两种提供方式二选一即可设置环境变量DOTTXT_API_KEY在实例化dottxt.client.DotTxt时通过api_key参数显式传入。测试代码 tests/models/test_dottxt.py 印证了这一设计api_keyfixture 优先读取环境变量DOTTXT_API_KEY未设置时回退到占位符MOCK_API_KEY用于不发起真实请求的初始化测试。这也说明 Dottxt 客户端允许先初始化、后调用Key 的校验发生在实际发起 API 请求时。模型初始化from_dottxt与客户端类型自动识别Outlines 中每个模型都对应一个from_前缀的加载函数参见 docs/features/models/index.md 的模型总览Dottxt 对应的加载函数是from_dottxt它定义在 src/outlines/models/dottxt.py并通过 src/outlines/models/init.py 导出为outlines.from_dottxt顶层 API。同步客户端from dottxt.client import DotTxt import outlines client DotTxt(api_key...) model outlines.from_dottxt(client, dottxt/dottxt-v1-alpha)第二个位置参数model是模型标识符可以直接在初始化时指定。若不确定自己的账号可用哪些模型可以调用client.models.list()获取当前账户可用的模型标识符列表。异步客户端from_dottxt不仅接受同步的DotTxt客户端也接受异步的AsyncDotTxt客户端它通过isinstance判断客户端类型并自动返回对应的封装类源码见 src/outlines/models/dottxt.pyfrom dottxt.client import AsyncDotTxt import outlines client AsyncDotTxt(api_key...) model outlines.from_dottxt(client, dottxt/dottxt-v1-alpha)此时返回的是outlines.models.dottxt.AsyncDottxt实例。若传入的客户端既不是DotTxt也不是AsyncDotTxtfrom_dottxt会抛出ValueError提示必须传入这两个类型之一的实例。从源码结构看Dottxt与AsyncDottxt只是对 SDK 客户端的薄封装thin wrapper它们持有client、model两个属性并共用一个DottxtTypeAdapter实例完成输入输出类型的转换src/outlines/models/dottxt.py、src/outlines/models/dottxt.py。两者在 src/outlines/models/init.py 中分别被归入BlackBoxModel黑盒模型与AsyncBlackBoxModel联合类型——所谓黑盒即文本生成发生在远端服务器Outlines 无法像本地模型那样通过 logits processor 直接干预生成过程。文本生成仅支持 JSON Schema 约束生成Dottxt 后端的一个重要约束是只支持带 JSON Schema 输出类型的约束生成不提供无约束自由生成。因此在调用时必须始终提供output_type参数。这一限制在源码中有明确体现。DottxtTypeAdapter.format_output_type的判定逻辑src/outlines/models/dottxt.py为output_type为None→ 抛出TypeErrorYou must provide an output type. Dottxt only supports constrained generation.传入Regex正则输出类型→ 抛出TypeError提示正则约束即将支持当前请改用开源本地模型传入CFG上下文无关文法→ 抛出TypeError同样提示即将支持传入可转换为 JSON Schema 的类型如 Pydantic 模型、dataclass、TypedDict、json_schema(...)包装的字符串/字典等→ 通过JsonSchema.convert_to转换后以字符串形式传给客户端其他不支持的简单类型如str、int→ 抛出TypeError提示该类型不受 Dottxt 支持建议改用本地模式。对应的类型适配测试 tests/models/test_dottxt_type_adapter.py 覆盖了上述全部分支None、str、int、regex(...)、cfg(...)均被拒绝dataclass、TypedDict、Pydantic 模型、gensonSchemaBuilder以及json_schema包装的字符串/字典都能成功转换为 JSON schema 字符串。测试还验证了format_input只接受str类型输入传入列表如[prompt, image]这种多模态输入会抛出TypeError——Dottxt 当前不支持视觉/多模态输入这也与 docs/features/models/index.md 特性矩阵中 Dottxt 在 Vision 一栏为 ❌ 的记录一致。同步调用from typing import List from pydantic import BaseModel from dottxt.client import DotTxt import outlines class Character(BaseModel): name: str age: int skills: List[str] model outlines.from_dottxt(DotTxt(), dottxt/dottxt-v1-alpha) result model(Create a character, Character) print(result) # {name: Evelyn, age: 34, skills: [archery, stealth, alchemy]} print(Character.model_validate_json(result)) # nameEvelyn, age34, skills[...]调用时传入 Pydantic 模型作为output_typeOutlines 会将其转换为 JSON Schema 字符串并通过response_format参数提交给 Dottxt 客户端src/outlines/models/dottxt.py返回结果是 JSON 字符串可直接用Character.model_validate_json反序列化为 Pydantic 实例。测试 tests/models/test_dottxt.py 验证了直接以 Pydantic 模型调用、以及通过Generator(model, User)复用生成器的两种方式都能得到包含目标字段的 JSON 结果。异步调用from typing import List from pydantic import BaseModel from dottxt.client import AsyncDotTxt import outlines class Character(BaseModel): name: str age: int skills: List[str] model outlines.from_dottxt(AsyncDotTxt(), dottxt/dottxt-v1-alpha) result await model(Create a character, Character) print(result) # {name: Evelyn, age: 34, skills: [archery, stealth, alchemy]}异步路径的实现与同步路径对称AsyncDottxt.generate同样先经DottxtTypeAdapter转换输入与输出类型再以await client.generate(...)发起请求src/outlines/models/dottxt.py。推理参数temperature、max_tokens、seed与模型覆盖dottxtSDK 的generate方法支持的任意可选参数都可以在调用时以关键字参数透传result model(Create a character, Character, temperature0.8, max_tokens256)常用的参数包括temperature采样温度、max_tokens最大生成长度、seed随机种子以及任何其他 OpenAI 兼容的 chat completion 参数。这些参数会通过**inference_kwargs原样传给底层 SDK 的generate方法如果传入了 SDK 不认识的参数会在请求发起时抛出TypeErrorgot an unexpected keyword argument对应测试见 tests/models/test_dottxt.py。模型标识符的优先级与缺失报错model参数既可以在初始化时固定也可以在每次调用时覆盖两者同时提供时以调用时的model为准result model(Create a character, Character, modeldottxt/other-model)源码中的优先级逻辑src/outlines/models/dottxt.py为若inference_kwargs中已有model则直接使用否则回退到初始化时设置的self.model如果两处都没有提供则抛出ValueErrorA model identifier is required...。测试 tests/models/test_dottxt.py 与异步版本 tests/models/test_dottxt.py 均验证了这一行为。因此model参数要么在from_dottxt(client, model)初始化时给定要么在每次调用时以model传入二者必居其一。错误处理与能力边界异常归一化Dottxt 的请求包裹在normalize_provider_errors(PROVIDER)上下文管理器内src/outlines/models/dottxt.py。该机制定义在 src/outlines/exceptions.py会把 Dottxt SDK 抛出的原始异常映射为 Outlines 统一的APIError异常体系例如urllib3的NewConnectionError、MaxRetryError→APIConnectionError连接失败可重试ConnectTimeoutError、ReadTimeoutError→APITimeoutError超时可重试携带 HTTP 状态码的异常按状态码映射401 →AuthenticationError、403 →PermissionDeniedError、404 →NotFoundError、429 →RateLimitError可重试、4xx →BadRequestError、5xx →ServerError可重试。具体映射表见 src/outlines/exceptions.py。这意味着你只需捕获outlines.exceptions.APIError及其子类即可统一处理 Dottxt 的鉴权失败、限流、超时等问题并通过异常的provider、status_code、request_id等属性定位问题src/outlines/exceptions.py。不支持的生成能力从源码可以确认 Dottxt 后端当前不支持批处理与流式生成generate_batch抛出NotImplementedError提示 Dottxt does not support batch generationsrc/outlines/models/dottxt.pygenerate_stream抛出NotImplementedError提示 Dottxt does not support streaming. Call the model/generator for regular generation insteadsrc/outlines/models/dottxt.py。对应测试 tests/models/test_dottxt.py 与异步版本 tests/models/test_dottxt.py 分别验证了model.stream(...)、model.batch(...)以及异步的async for流式都会抛出NotImplementedError。这与 docs/features/models/index.md 特性矩阵一致Dottxt 在 Streaming、Batching 栏均为 ❌在 Async 栏为 ❌——不过实际上本文所述的异步客户端场景传入AsyncDotTxt仍可获得异步的AsyncDottxt封装。能力定位小结根据 docs/features/models/index.md 的输出类型矩阵Dottxt 是典型的专精型后端仅支持 JSON Schema 输出类型✅不支持简单类型、多选、正则与文法输出。其核心使用范式可归纳为安装outlines[dottxt]配置DOTTXT_API_KEY或显式传入api_key用DotTxt同步或AsyncDotTxt异步创建客户端经outlines.from_dottxt(client, model)得到模型实例定义 Pydantic 模型或 dataclass/TypedDict/JSON Schema调用model(prompt, OutputType, ...)获取 JSON 字符串按需以关键字参数调整temperature、max_tokens、seed等推理参数或覆盖model标识符用outlines.exceptions.APIError统一捕获并处理限流、超时等 Provider 错误。当你需要云端托管 强 JSON Schema 约束 与本地模型一致的 Outlines 编程接口时Dottxt 是一个开箱即用的选择而如果你需要正则、文法或自由文本生成则应参考 docs/features/models/index.md 中的特性矩阵改用支持相应输出类型的本地模型或其他后端。【免费下载链接】outlinesStructured Outputs项目地址: https://gitcode.com/GitHub_Trending/ou/outlines创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Outlines 接入 Dottxt API：JSON Schema 结构化输出的云端模型集成指南
Outlines 接入 Dottxt APIJSON Schema 结构化输出的云端模型集成指南【免费下载链接】outlinesStructured Outputs项目地址: https://gitcode.com/GitHub_Trending/ou/outlinesOutlines 通过from_dottxt加载函数将 Dottxt 云端 API 封装为统一的模型接口让开发者无需关心底层传输协议即可获得 JSON Schema 约束的结构化生成能力。本文基于 docs/features/models/dottxt.md 展开结合 src/outlines/models/dottxt.py 的源码实现与 tests/models/test_dottxt.py 等测试用例完整讲解安装配置、同步/异步模型初始化、约束生成调用方式、推理参数覆盖以及错误类型归一化与能力边界等实战细节。读完本文你将掌握在 Outlines 项目中接入 Dottxt 云模型、用 Pydantic 模型约束输出并处理异常的标准姿势。环境准备安装与 API Key 配置Dottxt 是 Outlines 的可选后端需要单独安装其 Python SDK。在 pyproject.toml 中dottxt被声明为可选依赖组dottxt [dottxt]同时测试依赖要求dottxt0.2.0。安装命令如下pip install outlines[dottxt]安装完成后你还需要一个 Dottxt API Key。获取方式请参考 Outlines 官方文档在dottxt.md中通过官方申请表单入口获取。拿到 Key 后有两种提供方式二选一即可设置环境变量DOTTXT_API_KEY在实例化dottxt.client.DotTxt时通过api_key参数显式传入。测试代码 tests/models/test_dottxt.py 印证了这一设计api_keyfixture 优先读取环境变量DOTTXT_API_KEY未设置时回退到占位符MOCK_API_KEY用于不发起真实请求的初始化测试。这也说明 Dottxt 客户端允许先初始化、后调用Key 的校验发生在实际发起 API 请求时。模型初始化from_dottxt与客户端类型自动识别Outlines 中每个模型都对应一个from_前缀的加载函数参见 docs/features/models/index.md 的模型总览Dottxt 对应的加载函数是from_dottxt它定义在 src/outlines/models/dottxt.py并通过 src/outlines/models/init.py 导出为outlines.from_dottxt顶层 API。同步客户端from dottxt.client import DotTxt import outlines client DotTxt(api_key...) model outlines.from_dottxt(client, dottxt/dottxt-v1-alpha)第二个位置参数model是模型标识符可以直接在初始化时指定。若不确定自己的账号可用哪些模型可以调用client.models.list()获取当前账户可用的模型标识符列表。异步客户端from_dottxt不仅接受同步的DotTxt客户端也接受异步的AsyncDotTxt客户端它通过isinstance判断客户端类型并自动返回对应的封装类源码见 src/outlines/models/dottxt.pyfrom dottxt.client import AsyncDotTxt import outlines client AsyncDotTxt(api_key...) model outlines.from_dottxt(client, dottxt/dottxt-v1-alpha)此时返回的是outlines.models.dottxt.AsyncDottxt实例。若传入的客户端既不是DotTxt也不是AsyncDotTxtfrom_dottxt会抛出ValueError提示必须传入这两个类型之一的实例。从源码结构看Dottxt与AsyncDottxt只是对 SDK 客户端的薄封装thin wrapper它们持有client、model两个属性并共用一个DottxtTypeAdapter实例完成输入输出类型的转换src/outlines/models/dottxt.py、src/outlines/models/dottxt.py。两者在 src/outlines/models/init.py 中分别被归入BlackBoxModel黑盒模型与AsyncBlackBoxModel联合类型——所谓黑盒即文本生成发生在远端服务器Outlines 无法像本地模型那样通过 logits processor 直接干预生成过程。文本生成仅支持 JSON Schema 约束生成Dottxt 后端的一个重要约束是只支持带 JSON Schema 输出类型的约束生成不提供无约束自由生成。因此在调用时必须始终提供output_type参数。这一限制在源码中有明确体现。DottxtTypeAdapter.format_output_type的判定逻辑src/outlines/models/dottxt.py为output_type为None→ 抛出TypeErrorYou must provide an output type. Dottxt only supports constrained generation.传入Regex正则输出类型→ 抛出TypeError提示正则约束即将支持当前请改用开源本地模型传入CFG上下文无关文法→ 抛出TypeError同样提示即将支持传入可转换为 JSON Schema 的类型如 Pydantic 模型、dataclass、TypedDict、json_schema(...)包装的字符串/字典等→ 通过JsonSchema.convert_to转换后以字符串形式传给客户端其他不支持的简单类型如str、int→ 抛出TypeError提示该类型不受 Dottxt 支持建议改用本地模式。对应的类型适配测试 tests/models/test_dottxt_type_adapter.py 覆盖了上述全部分支None、str、int、regex(...)、cfg(...)均被拒绝dataclass、TypedDict、Pydantic 模型、gensonSchemaBuilder以及json_schema包装的字符串/字典都能成功转换为 JSON schema 字符串。测试还验证了format_input只接受str类型输入传入列表如[prompt, image]这种多模态输入会抛出TypeError——Dottxt 当前不支持视觉/多模态输入这也与 docs/features/models/index.md 特性矩阵中 Dottxt 在 Vision 一栏为 ❌ 的记录一致。同步调用from typing import List from pydantic import BaseModel from dottxt.client import DotTxt import outlines class Character(BaseModel): name: str age: int skills: List[str] model outlines.from_dottxt(DotTxt(), dottxt/dottxt-v1-alpha) result model(Create a character, Character) print(result) # {name: Evelyn, age: 34, skills: [archery, stealth, alchemy]} print(Character.model_validate_json(result)) # nameEvelyn, age34, skills[...]调用时传入 Pydantic 模型作为output_typeOutlines 会将其转换为 JSON Schema 字符串并通过response_format参数提交给 Dottxt 客户端src/outlines/models/dottxt.py返回结果是 JSON 字符串可直接用Character.model_validate_json反序列化为 Pydantic 实例。测试 tests/models/test_dottxt.py 验证了直接以 Pydantic 模型调用、以及通过Generator(model, User)复用生成器的两种方式都能得到包含目标字段的 JSON 结果。异步调用from typing import List from pydantic import BaseModel from dottxt.client import AsyncDotTxt import outlines class Character(BaseModel): name: str age: int skills: List[str] model outlines.from_dottxt(AsyncDotTxt(), dottxt/dottxt-v1-alpha) result await model(Create a character, Character) print(result) # {name: Evelyn, age: 34, skills: [archery, stealth, alchemy]}异步路径的实现与同步路径对称AsyncDottxt.generate同样先经DottxtTypeAdapter转换输入与输出类型再以await client.generate(...)发起请求src/outlines/models/dottxt.py。推理参数temperature、max_tokens、seed与模型覆盖dottxtSDK 的generate方法支持的任意可选参数都可以在调用时以关键字参数透传result model(Create a character, Character, temperature0.8, max_tokens256)常用的参数包括temperature采样温度、max_tokens最大生成长度、seed随机种子以及任何其他 OpenAI 兼容的 chat completion 参数。这些参数会通过**inference_kwargs原样传给底层 SDK 的generate方法如果传入了 SDK 不认识的参数会在请求发起时抛出TypeErrorgot an unexpected keyword argument对应测试见 tests/models/test_dottxt.py。模型标识符的优先级与缺失报错model参数既可以在初始化时固定也可以在每次调用时覆盖两者同时提供时以调用时的model为准result model(Create a character, Character, modeldottxt/other-model)源码中的优先级逻辑src/outlines/models/dottxt.py为若inference_kwargs中已有model则直接使用否则回退到初始化时设置的self.model如果两处都没有提供则抛出ValueErrorA model identifier is required...。测试 tests/models/test_dottxt.py 与异步版本 tests/models/test_dottxt.py 均验证了这一行为。因此model参数要么在from_dottxt(client, model)初始化时给定要么在每次调用时以model传入二者必居其一。错误处理与能力边界异常归一化Dottxt 的请求包裹在normalize_provider_errors(PROVIDER)上下文管理器内src/outlines/models/dottxt.py。该机制定义在 src/outlines/exceptions.py会把 Dottxt SDK 抛出的原始异常映射为 Outlines 统一的APIError异常体系例如urllib3的NewConnectionError、MaxRetryError→APIConnectionError连接失败可重试ConnectTimeoutError、ReadTimeoutError→APITimeoutError超时可重试携带 HTTP 状态码的异常按状态码映射401 →AuthenticationError、403 →PermissionDeniedError、404 →NotFoundError、429 →RateLimitError可重试、4xx →BadRequestError、5xx →ServerError可重试。具体映射表见 src/outlines/exceptions.py。这意味着你只需捕获outlines.exceptions.APIError及其子类即可统一处理 Dottxt 的鉴权失败、限流、超时等问题并通过异常的provider、status_code、request_id等属性定位问题src/outlines/exceptions.py。不支持的生成能力从源码可以确认 Dottxt 后端当前不支持批处理与流式生成generate_batch抛出NotImplementedError提示 Dottxt does not support batch generationsrc/outlines/models/dottxt.pygenerate_stream抛出NotImplementedError提示 Dottxt does not support streaming. Call the model/generator for regular generation insteadsrc/outlines/models/dottxt.py。对应测试 tests/models/test_dottxt.py 与异步版本 tests/models/test_dottxt.py 分别验证了model.stream(...)、model.batch(...)以及异步的async for流式都会抛出NotImplementedError。这与 docs/features/models/index.md 特性矩阵一致Dottxt 在 Streaming、Batching 栏均为 ❌在 Async 栏为 ❌——不过实际上本文所述的异步客户端场景传入AsyncDotTxt仍可获得异步的AsyncDottxt封装。能力定位小结根据 docs/features/models/index.md 的输出类型矩阵Dottxt 是典型的专精型后端仅支持 JSON Schema 输出类型✅不支持简单类型、多选、正则与文法输出。其核心使用范式可归纳为安装outlines[dottxt]配置DOTTXT_API_KEY或显式传入api_key用DotTxt同步或AsyncDotTxt异步创建客户端经outlines.from_dottxt(client, model)得到模型实例定义 Pydantic 模型或 dataclass/TypedDict/JSON Schema调用model(prompt, OutputType, ...)获取 JSON 字符串按需以关键字参数调整temperature、max_tokens、seed等推理参数或覆盖model标识符用outlines.exceptions.APIError统一捕获并处理限流、超时等 Provider 错误。当你需要云端托管 强 JSON Schema 约束 与本地模型一致的 Outlines 编程接口时Dottxt 是一个开箱即用的选择而如果你需要正则、文法或自由文本生成则应参考 docs/features/models/index.md 中的特性矩阵改用支持相应输出类型的本地模型或其他后端。【免费下载链接】outlinesStructured Outputs项目地址: https://gitcode.com/GitHub_Trending/ou/outlines创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考