Structured outputs appear to be ignored for MLX models

快速结论：这个报错发生在 Ollama 的 MLX 执行路径上——当通过 format 字段传入 JSON Schema 时，MLX runner 会直接丢弃该字段，导致模型完全无视 schema 约束，返回自然语言而不是结构化 JSON。优先排查方式是确认当前模型是否真的走 MLX 引擎，并回退到非 MLX 模型。

适用环境：Ollama 0.30.6 及更高版本（已复核到 v0.32.5）；macOS（含 Apple Silicon / M1）；涉及模型包括 Qwen 3.5/3.6 系列、Gemma 4 系列及其对应 -mlx 后缀版本。

最快修复方案：暂无确认的一步修复方案。Issue 确认 MLX runner 目前不支持约束采样，且 format 字段不会传给 MLX 执行器；作为变通，先改用不带 -mlx 后缀的对应模型（如 qwen3.5:4b 而非 qwen3.5:4b-mlx）来获得 schema 约束。

注意事项：这是 MLX 引擎的功能缺失，不是模型质量问题。即使 HTTP 请求返回 200，输出也没有经过 schema 约束；在你确认 MLX 引擎实现约束采样之前，不要在生产环境依赖 MLX 模型的 format 输出。

问题场景

在 macOS 上通过 Ollama 的 /api/chat 或 /api/generate 接口请求 JSON Schema 结构化输出时，使用带 -mlx 后缀的模型（如 qwen3.5:4b-mlx、gemma4:31b-mlx）会出现 schema 被完全忽略的情况：模型返回自然语言问候或无法解析的 JSON-like 文本，而不是符合 format 定义的 JSON。

同样的问题也影响 OpenAI 兼容接口的 response_format 参数，且与流式（stream）还是非流式请求无关。Issue 中确认了多个 MLX 模型族在结构化评测中均出现 0/5 通过率，而同一模型的非 MLX 版本通过率正常。

报错原文

Structured outputs appear to be ignored for MLX models

qwen3.5:4b
{"animal": "👋 Hey there! Hello! How can I help you with today? 😊"}

qwen3.5:4b-mlx
Hi there! 👋 How's it going? Anything I can help you with today?

gemma4:31b
-> schema-conforming JSON

gemma4:31b-mlx
-> natural-language greeting

原因分析

可能原因（已通过源码检查确认）：llm.CompletionRequest.Format 字段没有被复制到 x/mlxrunner.CompletionRequest，即 MLX runner 在构造请求时直接丢弃了 format 参数，schema 从未到达执行器。此外，MLX 采样器目前没有任何 grammar / JSON Schema 约束采样实现。两者叠加导致 format: "json" 和 JSON Schema 请求即使返回 HTTP 200，也从未真正被约束过。

这解释了为什么 MLX 模型并非“生成错误格式”，而是根本没有看到 schema——输出完全是模型对 prompt 的自然响应。这与模型家族无关，只与是否走 MLX 执行路径有关。

环境排查

确认 Ollama 版本：Issue 在 0.30.6 中发现，v0.32.5 上仍可复现。
确认模型确实走 MLX runner：日志中应出现 starting mlx runner subprocess，且模型标签带 -mlx 后缀。
对比测试：用同一家族的非 MLX 模型（如 qwen3.5:4b 而非 qwen3.5:4b-mlx）确认 schema 约束生效。
检查调用方式：format 字段传的是 JSON Schema 对象（而非仅字符串 "json"）时同样受影响。
排查应用的 HTTP 状态码判断逻辑：MLX 请求返回 200 不代表输出已满足 schema，需要额外校验响应内容。

解决步骤

临时方案：优先使用不带 -mlx 后缀的模型（如 qwen3.5:4b 代替 qwen3.5:4b-mlx），因为非 MLX 路径支持约束采样，能正确应用 schema。
如果你必须使用 MLX 模型，建议在应用层对响应结果做额外的 schema 校验（如用 JSON Schema validator），不要信任 HTTP 200 即代表输出合规。
目前没有可用的修复版本让 MLX 支持 format。可优先尝试跟踪 PR #17232 的进展，它会将“静默忽略 schema”改为“返回明确的 4xx 错误”以快速暴露问题；但这只是失败快速化，并非功能补齐。
长期等待方案：关注 Ollama 是否在 MLX 引擎中实现约束采样（grammar / JSON Schema），Issue 作者明确要求 /api/chat、/api/generate、OpenAI 兼容 response_format 均保持一致，且要覆盖流式与非流式、思考模型等场景。
如果你需要给团队或用户明确提示，可以在应用层检测到“MLX 镜像 + format 请求”时主动报错提示功能不可用，避免静默返回未约束输出。

验证方法

用同一 prompt 和 schema 分别请求 MLX 版本和非 MLX 版本模型，检查输出是否均为合法 JSON 且满足 schema 约束。如果 MLX 版本仍返回自然语言文本或无法解析的 JSON-like 内容，说明问题未解决；只有当 MLX 版本输出同样符合 format 约束时才算修复。对于已应用快速失败方案的版本，可通过请求应返回 4xx 响应来确认修复生效。