mistral.rs OpenAI 兼容性完全指南字段级兼容矩阵、Responses API 与扩展能力详解【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsmistral.rs 以字段级field-levelOpenAI 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 UIhttp://localhost:1234/docs与原始 OpenAPI 文档GET /api-doc/openapi.json可随时核对当前构建的完整请求/响应 schema详见 HTTP API 语义参考。端点地图端点用途GET /v1/models列出已加载的基础模型与 LoRA 别名模型卡片POST /v1/chat/completions对话、流式、工具调用、多模态输入及 mistral.rs 代理扩展POST /v1/responsesOpenAI Responses API响应对象、轮询、后台运行、取消POST /v1/skills上传 OpenAI 兼容 SkillsGET /v1/skills列出已上传的 SkillsGET, POST /v1/skills/{skill_id}/versions列出或上传既有 Skill 的版本POST /v1/completions传统文本补全POST /v1/embeddings向量生成POST /v1/images/generations图像生成POST /v1/audio/speech文本转语音POST /v1/files上传 OpenAI 兼容用户文件GET /v1/files列出已上传与生成的文件POST /v1/load_lora_adapter加载本地 LoRA 适配器或以load_inplace原子替换需启用运行时更新GET /v1/lora_adapters列出已加载的 LoRA 别名、代次与容量路由始终注册目标模型需启用动态 LoRAPOST /v1/unload_lora_adapter卸载 LoRA 别名需启用运行时更新更完整的服务端配置方式端口、多模型、CORS、认证、日志等见 serve 命令参考 与 TOML 配置参考。二、Chat Completions字段级兼容矩阵2.1 已实现的标准字段以下 OpenAI Chat Completions 字段在 mistral.rs 上原生可用modelmessages包含多模态 content partsmax_tokensmax_completion_tokensOpenAI 对max_tokens的新别名temperaturetop_pstreamstoptools、tool_choiceresponse_formattext、json_schemalogit_biaslogprobs、top_logprobspresence_penalty、frequency_penaltyn多路补全从源码看这些字段在 mistralrs-server-core/src/chat_completion.rs 中逐项被解析并映射到引擎内部请求例如max_tool_rounds会与服务器级默认值取优先级oairequest.max_tool_rounds.or(agentic_defaults.max_tool_rounds)truncate_sequence默认falseoairequest.truncate_sequence.unwrap_or(false)。2.2 已实现但有偏差的字段字段支持情况偏差说明tool_choice支持auto、none、required、Chat Completions 形式的具体函数对象{type:function,function:{name:...}}、Responses 形式的具体函数对象{type:function,name:...}、以及{type:allowed_tools,mode:auto\|required,tools:[{type:function,name:...}]}required在无可用工具时会拒绝请求allowed_tools仅适用于函数工具子集tools[*].function.strict函数工具接受该字段为true时 mistral.rs 会把生成的工具参数约束到该工具的parametersJSON Schema参见工具调用基础tools[*].typecode_interpreter作为内置 Python 执行器的 OpenAI 兼容开关服务器必须以代码执行模式启动仅支持容器形式{type:auto}容器 id、container.file_ids、container.memory_limit及 OpenAI 容器生命周期端点均不支持messages[].content[]文件 parts支持{type:file,file:{file_id:file-...}}与{type:file,file:{filename:data.csv,file_data:data:text/csv;base64,...}}Chat Completions 的文件 URL 不支持需先上传文件或改用 Responsesresponse_formatjson_schema支持模糊 schema 下输出形态可能与 OpenAI 有差异json_object不被接受参见结构化输出seed支持初始化确定性的请求级采样流多路补全多个 choices时为每个 choice 派生独立采样流2.3 静默忽略的字段user、stream_options、metadata、service_tier、parallel_tool_calls、store会被请求体接受未知字段不会被拒绝但没有对应行为被接线。若需要持久化请使用 mistral.rs 的session_id。2.4 mistral.rs 扩展请求控制除基础字段外Chat Completions 还接受下列字段其中一部分是 mistral.rs 专有扩展字段作用top_k硬性候选截断上限min_pmin-p 采样阈值repetition_penalty比 frequency/presence 更简单的重复惩罚替代方案dry_multiplier、dry_base、dry_allowed_length、dry_sequence_breakersDRY 采样参数grammar超越 JSON Schema 的 llguidance 约束reasoning_effortoff、low、medium、high、xhighnone是off的别名值会被裁剪且大小写不敏感enable_thinking传统布尔开关详见下文推理控制解析规则web_search_options搜索工具配置OpenAI 事实标准字段尚未被所有平台采用session_id多轮会话持久化files服务端代码执行所需的输出文件agent_permission、code_execution_permission对服务端执行工具的按请求权限收紧max_tool_rounds限制单请求的服务端工具循环轮数truncate_sequence在模型上下文上限处截断超长提示而不是报错adapter选择已加载的动态 LoRA 别名字符串或精确的不可变代次对象{generation:generation-id}省略或传null表示基础模型未知别名、非驻留代次、无动态 LoRA 运行时的模型都会返回错误推理控制的底层解析规则enable_thinking与reasoning_effort的语义在 mistralrs-core/src/request.rs 的resolve_reasoning_controls中实现两者都省略时启用 thinkingeffort 保持未指定显式给出正向 effort启用 thinkingreasoning_effort: off关闭 thinking矛盾组合如reasoning_effort: off配enable_thinking: true返回校验错误对应ReasoningControlError::OffWithThinkingEnabledenable_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_generationResponses 的已完成资源同样携带该字段基础模型请求则省略此字段。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 APIPOST /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_urlprevious_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、storestore默认truestore: 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 APIPOST /v1/skills以 multipart 表单数据上传一个 OpenAI 兼容 Skillfiles字段可包含 zip 压缩包或某个顶级 Skill 目录下的所有文件顶级目录必须含带name、descriptionfrontmatter 的SKILL.mdGET /v1/skills列出当前服务器进程与 skills 目录下的已上传 SkillPOST /v1/skills/{skill_id}/versions为既有 Skill 上传新版本。上传的 Skill 版本存放在服务器的 skills 目录--skills-dir默认系统临时目录被引用的 Skill 会提供给 Shell 会话。更详细的上传与执行流程见 Skills 指南 与可运行示例 examples/server/skills.py。3.4 被拒绝的非默认值Responses 端点对下列值直接报错而非静默忽略字段限制parallel_tool_calls必须为true默认或省略传false报错max_tool_calls任何值都报错限制工具轮数请用服务器级--max-tool-rounds标志对 Chat Completions 与 Responses 均生效tools[*].typeweb_search拒绝图像搜索search_content_types: [image]或image_settings与external_web_access: false支持最多 100 个允许/屏蔽域名的域过滤器含子域tools[*].typeweb_search_preview拒绝filters与return_token_budgetexternal_web_access被忽略tools[*].typecode_interpreter拒绝容器 id、container.file_ids、container.memory_limittools[*].typeshell拒绝本地环境、容器引用、本地 Skill 路径、内联/容器创建的 Skill 与 OpenAI 容器生命周期 API支持已上传的skill_reference3.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.effortoff、low、medium、high、xhighnone是off的别名省略时启用 thinking 但不指定 effortreasoning.summary为兼容而接受但目前不改变响应truncation用于序列截断。顶层enable_thinking、reasoning_effort、truncate_sequence键在该端点上被静默忽略。源码中reasoning.encrypted_content选项OpenAI 加密推理内容不被支持普通推理内容始终包含见 responses.rsbackground: 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 Completionslegacy/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 Embeddingsinput接受字符串或字符串列表encoding_formatfloat默认或base64dimensions传任意值都报错不支持自定义维度user接受但不使用。扩展truncate_sequence——在模型上下文上限处截断超长提示而非报错。4.3 图像生成Image Generationpromptnresponse_formatUrl默认url携带服务端文件名或B64Jsonb64_json携带data:image/png;base64,...字符串。OpenAI 的size字符串如1024x1024不支持改用height默认 720与width默认 1280。quality、style、steps、guidance_scale被忽略。4.4 音频Audio/v1/audio/speechTTSmodel、input支持response_format仅接受wav与pcmmp3、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 APIsPOST /v1/filesmultipart 上传支持用户输入文件OpenAI 兼容的请求附件请使用purposeuser_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 Tokenizationmistral.rs 不暴露/v1/tokenize或/v1/detokenizeHTTP 端点。分词器访问通过 SDK 提供Python 为tokenize_text/detokenize_textRust 为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、filesFile对象数组、adapter_generation实际使用的不可变 LoRA 代次基础模型请求省略。usage对象是 OpenAI 的超集额外提供avg_tok_per_sec、avg_prompt_tok_per_sec、avg_compl_tok_per_sec等计时字段。5.3 流式事件速查POST /v1/chat/completionsSSE匿名data:行携带 OpenAI 格式分片data: [DONE]终止命名事件agentic_tool_call_progress工具循环进度、agentic_tool_approval_required待审批、file_produced文件产出表达代理时间线POST /v1/responsesOpenAI 命名 Responses 事件见 3.6 节POST /v1/messagesAnthropic 命名事件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示例演示内容chat.py基础 Chat Completions 请求streaming.pyChat Completions 流式输出tool_calling.pyOpenAI 兼容函数工具allowed_tools.pyOpenAI 兼容allowed_tools函数子集选择openai_response_format.py通过response_format结构化输出responses.pyResponses API 请求responses_tools.pyResponses 宿主工具Web 搜索与代码解释器skills.pyOpenAI 兼容 Skills 上传与执行responses_vision.py带图像输入的 Responses APIweb_search.py通过 OpenAI 兼容字段搜索adapter_chat.py动态 LoRA 适配器路由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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考