企业官网建设流程全解析

mistral.rs OpenAI 兼容性完全指南：字段级兼容矩阵、Responses API 与扩展能力详解

【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs

mistral.rs 以字段级（field-level）OpenAI API 兼容为设计目标，绝大多数 OpenAI 客户端库无需改动即可对接其/v1端点。本文以官方兼容性参考为骨架，逐项梳理 Chat Completions、Responses、Completions、Embeddings、图像生成、音频、文件等端点的已实现字段、有偏差实现、静默忽略字段与 mistral.rs 专有扩展，并结合仓库源码（mistralrs-server-core/src/chat_completion.rs、mistralrs-server-core/src/responses.rs、mistralrs-core/src/request.rs）说明底层行为。读完本文，你将能判断任意 OpenAI 客户端请求能否原样跑通，也知道如何在保留 OpenAI 协议的同时使用 LoRA 路由、会话持久化、推理控制、服务端工具等增强能力。

一、兼容性总览：从启动到端点地图

mistralrs serve将本地模型暴露为位于/v1下的 OpenAI 兼容端点，OpenAI SDK 与各类兼容客户端只需把 base URL 指向http://localhost:1234/v1即可使用：

mistralrs serve -m Qwen/Qwen3-4B

随后发送一个最朴素的 Chat Completions 请求：

curl http://localhost:1234/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "default", "messages": [ {"role": "user", "content": "Write a haiku about local inference."} ], "max_tokens": 128 }'

单模型场景下请求中的model固定为"default"（也可省略）；多模型服务时使用GET /v1/models中出现的真实模型 id。服务端还自带 Swagger UI（http://localhost:1234/docs）与原始 OpenAPI 文档（GET /api-doc/openapi.json），可随时核对当前构建的完整请求/响应 schema，详见 HTTP API 语义参考。

端点地图

更完整的服务端配置方式（端口、多模型、CORS、认证、日志等）见 serve 命令参考 与 TOML 配置参考。

二、Chat Completions：字段级兼容矩阵

2.1 已实现的标准字段

以下 OpenAI Chat Completions 字段在 mistral.rs 上原生可用：

• model
• messages（包含多模态 content parts）
• max_tokens
• max_completion_tokens（OpenAI 对max_tokens的新别名）
• temperature
• top_p
• stream
• stop
• tools、tool_choice
• response_format（text、json_schema）
• logit_bias
• logprobs、top_logprobs
• presence_penalty、frequency_penalty
• n（多路补全）

从源码看，这些字段在 mistralrs-server-core/src/chat_completion.rs 中逐项被解析并映射到引擎内部请求：例如max_tool_rounds会与服务器级默认值取优先级（oairequest.max_tool_rounds.or(agentic_defaults.max_tool_rounds)），truncate_sequence默认false（oairequest.truncate_sequence.unwrap_or(false)）。

2.2 已实现但有偏差的字段

2.3 静默忽略的字段

user、stream_options、metadata、service_tier、parallel_tool_calls、store会被请求体接受（未知字段不会被拒绝），但没有对应行为被接线。若需要持久化，请使用 mistral.rs 的session_id。

2.4 mistral.rs 扩展请求控制

除基础字段外，Chat Completions 还接受下列字段，其中一部分是 mistral.rs 专有扩展：

推理控制的底层解析规则

enable_thinking与reasoning_effort的语义在 mistralrs-core/src/request.rs 的resolve_reasoning_controls中实现：

• 两者都省略时：启用 thinking，effort 保持未指定；
• 显式给出正向 effort：启用 thinking；
• reasoning_effort: "off"：关闭 thinking；
• 矛盾组合（如reasoning_effort: "off"配enable_thinking: true）返回校验错误，对应ReasoningControlError::OffWithThinkingEnabled；enable_thinking: false配正向 effort 则触发EffortWithThinkingDisabled。

选定的 effort 会同时以reasoning_effort与兼容名reasoning_strength传给聊天模板，由模板决定各档位如何影响模型——模板可以把正向档位等同处理，也可以忽略它不用的控制项。Python SDK 使用相同的取值与默认值。在 Chat Completions 请求体中，这些推理字段也可通过扩展字段（如enable_thinking放在顶层）传入，服务端在 chat_completion.rs 中统一归并解析。

2.5 动态 LoRA 的路由与管理

已加载的动态 LoRA 别名会从GET /v1/models获得稳定的限定模型卡片 id，可直接作为model发送。使用时必须使用返回的确切 id 而非自行拼接——保留字符会被转义，冲突时追加后缀。vLLM 风格的短别名路由同样受支持。模型卡片中：

• parent标识基础模型；
• root使用公开适配器别名而非本地文件系统路径；
• adapter_generation标识当前不可变代次。

当调用方需要独立的基座模型路由或精确代次时，使用上文adapter扩展字段。Chat Completions 与 Completions 的响应（含流式分片）都会暴露实际解析到的代次adapter_generation，Responses 的已完成资源同样携带该字段；基础模型请求则省略此字段。

GET /v1/lora_adapters路由始终注册，为动态 LoRA 启动的模型返回详细的别名、代次与容量状态；无该运行时的模型返回 409 与lora_runtime_unavailable。适配器来源默认打码，仅在启用运行时变更时公开。使用mistralrs serve时，POST /v1/load_lora_adapter与POST /v1/unload_lora_adapter需要环境变量MISTRALRS_ALLOW_RUNTIME_LORA_UPDATING（取值1/true/yes/on）；嵌入式服务器则通过LoraAdapterApiConfig配置变更能力。只读发现不需要变更权限。更完整的别名、代次与安全约束见 LoRA 适配器指南。

三、Responses API：响应对象、轮询与后台运行

mistral.rs 在 Chat Completions 之外完整实现了 OpenAI Responses API：

• POST /v1/responses：创建响应，返回带唯一 id 的响应对象；
• GET /v1/responses/{id}：获取已存储响应的当前状态；
• DELETE /v1/responses/{id}：删除已存储的响应；
• POST /v1/responses/{id}/cancel：取消尚未完成的后台响应。

适用场景：客户端期望 OpenAI Responses 对象形态、需要响应 id、需要轮询或后台处理、需要取消。而 Chat Completions 在单条连接上返回完整响应。Codex 说 Responses API，参见编码代理指南。

3.1 已实现字段

• input：消息列表或原始提示字符串
• input_filecontent parts：支持file_id、file_data、file_url
• previous_response_id：延续已存储的对话
• max_output_tokens：以max_tokens、max_completion_tokens为别名
• instructions、temperature、top_p、stop、stream、tools、tool_choice、response_format、logit_bias、logprobs、top_logprobs、presence_penalty、frequency_penalty、n、metadata、background、store

store默认true；store: false会跳过缓存，使响应无法被GET /v1/responses/{id}与previous_response_id访问。函数工具支持strict: true，与 Chat Completions 一样做 JSON-Schema 约束的参数生成。从 mistralrs-server-core/src/responses.rs 可见，Responses 的reasoning.effort与truncation会在服务端被转换为内部推理控制与truncate_sequence布尔值后复用 Chat Completions 引擎路径。

3.2tools的三种形态

Responses 的tools数组接受：

• Responses 扁平形式函数工具：{"type":"function","name":"...","parameters":{...}}
• Chat Completions 嵌套形式函数工具：{"type":"function","function":{...}}
• 服务端 Web 搜索：{"type":"web_search", ...}与{"type":"web_search_preview"}
• 服务端 Python 代码执行：{"type":"code_interpreter","container":{"type":"auto"}}
• 服务端 Shell 执行与 OpenAI 兼容 Skills：{"type":"shell","environment":{"type":"container_auto","skills":[{"type":"skill_reference","skill_id":"skill_...","version":"latest"}]}}

Skills 依赖 Shell 执行器，因此服务器至少要带--enable-shell启动；若同时想要完整代理运行时，推荐--agent预设。

tool_choice: "required"被接受，且在未提供工具时拒绝请求；具体的函数选择必须引用已声明的函数工具。tool_choice: {"type":"allowed_tools", ...}仅支持函数工具子集。宿主工具（hosted tool）的强制选择或过滤不支持，例如{"type":"web_search_preview"}、{"type":"code_interpreter"}、{"type":"shell"}或把宿主工具放进allowed_tools。

3.3 Skills API

• POST /v1/skills：以 multipart 表单数据上传一个 OpenAI 兼容 Skill，files字段可包含 zip 压缩包或某个顶级 Skill 目录下的所有文件；顶级目录必须含带name、descriptionfrontmatter 的SKILL.md；
• GET /v1/skills：列出当前服务器进程与 skills 目录下的已上传 Skill；
• POST /v1/skills/{skill_id}/versions：为既有 Skill 上传新版本。

上传的 Skill 版本存放在服务器的 skills 目录（--skills-dir，默认系统临时目录），被引用的 Skill 会提供给 Shell 会话。更详细的上传与执行流程见 Skills 指南 与可运行示例 examples/server/skills.py。

3.4 被拒绝的非默认值

Responses 端点对下列值直接报错（而非静默忽略）：

3.5 Responses 上的 mistral.rs 扩展

top_k、min_p、repetition_penalty、dry_multiplier、dry_base、dry_allowed_length、dry_sequence_breakers、grammar、adapter同样可用于 Responses。adapter字段选择已加载的动态 LoRA 别名或精确代次对象；省略或null表示基础模型；已加载的别名也可作为model发送。聊天专属的代理字段（session_id、agent_permission、files、max_tool_rounds、web_search_options）不属于该端点的 schema，请改用 Responses 的tools数组表达 Web 搜索、代码执行、Shell 与 OpenAI 兼容 Skills。

推理控制在该端点不是顶层扩展字段，而是通过标准 Responses 对象表达：

• reasoning.effort：off、low、medium、high、xhigh；none是off的别名；省略时启用 thinking 但不指定 effort；
• reasoning.summary：为兼容而接受，但目前不改变响应；
• truncation：用于序列截断。

顶层enable_thinking、reasoning_effort、truncate_sequence键在该端点上被静默忽略。源码中reasoning.encrypted_content选项（OpenAI 加密推理内容）不被支持，普通推理内容始终包含（见 responses.rs）；background: true与stream: true组合会返回unsupported_background_stream_error。

3.6 后台运行与轮询示例

curl http://localhost:1234/v1/responses \ -H "Content-Type: application/json" \ -d '{ "model": "default", "input": "Summarize today in tech news.", "background": true }'

轮询：curl http://localhost:1234/v1/responses/<id>；取消：curl -X POST http://localhost:1234/v1/responses/<id>/cancel。流式响应使用 OpenAI 命名事件：生命周期与增量事件包括response.created、response.in_progress、response.output_item.added、response.content_part.added、response.output_text.delta、response.content_part.done、response.output_item.done、response.function_call_arguments.delta、response.function_call_arguments.done；终止事件恰有一个：response.completed（成功）、response.failed（出错）或response.incomplete（提前停止，如触达 token 上限）。错误还会以命名error事件流式下发；mistral.rs 的agentic_tool_call_progress与file_produced事件同样会出现在该端点上，Shell 工具调用以 Responsesshell_call与shell_call_output输出项表示。完整流式语义见 HTTP API 语义参考。

四、其余端点的兼容边界

4.1 Completions（legacy）

/v1/completions（非对话）支持 Chat Completions 扩展的子集：top_k、min_p、repetition_penalty、dry_multiplier、dry_base、dry_allowed_length、dry_sequence_breakers、grammar、truncate_sequence、adapter。LoRA 接受与 Chat Completions 相同的别名-as-model、适配器别名与精确代次形式。代理、会话、文件、Web 搜索、thinking 与推理 effort 字段不属于该端点 schema，传了也不生效。

4.2 Embeddings

• input：接受字符串或字符串列表；
• encoding_format："float"（默认）或"base64"；
• dimensions：传任意值都报错，不支持自定义维度；
• user：接受但不使用。

扩展：truncate_sequence——在模型上下文上限处截断超长提示而非报错。

4.3 图像生成（Image Generation）

• prompt
• n
• response_format："Url"（默认，url携带服务端文件名）或"B64Json"（b64_json携带data:image/png;base64,...字符串）。

OpenAI 的size字符串（如"1024x1024"）不支持，改用height（默认 720）与width（默认 1280）。quality、style、steps、guidance_scale被忽略。

4.4 音频（Audio）

/v1/audio/speech（TTS）：

• model、input：支持；
• response_format：仅接受wav与pcm；mp3、opus、aac、flac返回校验错误；
• voice、instructions、speed：忽略。

/v1/audio/transcriptions与/v1/audio/translations不作为独立端点暴露。Voxtral 等 STT 模型通过/v1/chat/completions携带音频 content parts 使用，参见语音模型指南。

4.5 Moderation

不支持。mistral.rs 没有内置审核模型；如需要请作为独立服务运行。

4.6 Files 与 Assistants APIs

POST /v1/filesmultipart 上传支持用户输入文件，OpenAI 兼容的请求附件请使用purpose="user_data"。已上传文件、请求内联文件、URL 拉取文件与代理生成文件均可通过GET /v1/files、GET /v1/files/{id}、GET /v1/files/{id}/content、DELETE /v1/files/{id}访问。

文本类 UTF-8 文件以有界解码预览形式暴露给模型（单文件 4096 字符、单请求 32768 字符；代理运行时开启文件访问后可查看更多文本）；二进制文件会被存储、可下载，并在 Shell/代码执行激活时挂载进工作目录，但 mistral.rs不做OpenAI 的私有 PDF/图像/表格提取流水线。Assistants API 不支持，其 mistral.rs 等价物是 chat completions 端点上的基于会话的代理循环。文件线协议细节见 HTTP API 语义参考 的“文件线 schema 与语义”一节。

4.7 Fine-tuning 与 Batch

不支持。mistral.rs 是推理引擎而非训练平台。

4.8 Tokenization

mistral.rs 不暴露/v1/tokenize或/v1/detokenizeHTTP 端点。分词器访问通过 SDK 提供：Python 为tokenize_text/detokenize_text，Rust 为tokenize_with_model/detokenize_with_model。

五、认证、响应头与流式协议语义

5.1 认证

OpenAI 协议要求Authorization: Bearer ...头。mistral.rs不校验该头，需要 API key 才能初始化的客户端可发送任意非空字符串。真正的认证请在前端放置认证反向代理（默认--host 0.0.0.0接受网络上任意主机的连接，暴露到公网前务必用--host 127.0.0.1或反向代理收口，详见 OpenAI 兼容 API 服务指南 与 HTTP API 语义参考）。

5.2 响应头与扩展响应字段

非流式响应Content-Type: application/json，流式响应为text/event-stream。会话 id（已分配或匹配到时）位于响应体的session_id字段而非响应头。

非流式 Chat 响应还在 OpenAI 形态之外携带四个 mistral.rs 字段（为空时省略）：session_id（后续请求复用以跨消息保持代理状态）、agentic_tool_calls（代理循环中工具调用的有序记录，含round、name、arguments、result_content，以及可选的result_images_base64与file_ids）、files（File对象数组）、adapter_generation（实际使用的不可变 LoRA 代次，基础模型请求省略）。usage对象是 OpenAI 的超集，额外提供avg_tok_per_sec、avg_prompt_tok_per_sec、avg_compl_tok_per_sec等计时字段。

5.3 流式事件速查

• POST /v1/chat/completions：SSE，匿名data:行携带 OpenAI 格式分片，data: [DONE]终止；命名事件agentic_tool_call_progress（工具循环进度）、agentic_tool_approval_required（待审批）、file_produced（文件产出）表达代理时间线；
• POST /v1/responses：OpenAI 命名 Responses 事件（见 3.6 节）；
• POST /v1/messages：Anthropic 命名事件（message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop）。

审批流：agent_permission: "ask"要求 HTTP 请求必须stream: true，非流式请求返回校验错误；审批通过POST /v1/agent/approvals/{approval_id}应答，未应答的审批 5 分钟后自动拒绝，详见 权限与审批。

六、从参考到实战：示例与验证路径

仓库examples/server/下提供了可直接运行的开箱示例（先启动mistralrs serve，再运行python examples/server/xxx.py）：

Python SDK 侧的使用方式（含base_url、api_key占位、extra_body={"adapter": ...}传 LoRA 等）见 OpenAI 兼容 API 服务指南；代理运行时的时间线、生成文件、搜索、代码执行、Shell、Skills 与会话状态见 代理运行时；会话持久化与拼接语义见 会话持久化指南。

结语

mistral.rs 的 OpenAI 兼容层不是“跑得通大多数客户端”的黑盒，而是一张可精确查询的字段级兼容矩阵：核心对话与补全字段完整实现，工具、结构化输出、多模态与文件输入带明确偏差，user/metadata等字段静默接受但无行为接线，同时通过top_k、min_p、DRY、grammar、reasoning_effort、session_id、adapter等扩展在 OpenAI 协议内叠加了采样控制、推理控制、会话持久化与 LoRA 路由能力。Responses API 的引入进一步补齐了响应对象、轮询、后台运行与取消等面向 Codex 类代理客户端的场景。判断一个请求能否原样跑通，只需对照本文矩阵，并在运行中的服务上通过http://localhost:1234/docs的 Swagger UI 与GET /api-doc/openapi.json核对实时 schema。

【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs