mistral.rs Rust SDK 实战将 LLM 推理引擎内嵌进 Rust 程序【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsmistralrscrate 将 mistral.rs 的推理引擎直接嵌入到 Rust 进程中让你在无需启动独立 HTTP 服务的前提下于进程内加载模型、发送对话请求并消费流式输出。本文以 Rust SDK 指南 为核心骨架结合 SDK 参考 与 Model 实现源码系统讲解从工程搭建、首次推理、流式响应处理到把整套 HTTP API 挂载进现有 Axum 应用的完整路径。读完本文你将掌握ModelBuilder/Model的完整调用面、Response流式变体处理范式以及mistralrs-server-core两个关键 builder 的嵌入用法。一、Rust SDK 是什么Rust SDK 的核心价值是“进程内推理”不需要/v1/chat/completions端点也没有 OpenAI 兼容层请求直接走 Rust 内部通道。这一点从 Model 源码 可以印证——Model结构内部仅持有一个ArcMistralRs引擎句柄而Streama则是对tokio::sync::mpsc::ReceiverResponse的封装并通过实现futures::Streamtrait 对外提供poll_next能力pub struct Streama { _server: a Model, rx: ReceiverResponse, } impl futures::Stream for Stream_ { type Item Response; fn poll_next(mut self: Pinmut Self, cx: mut TaskContext_) - PollOptionSelf::Item { self.rx.poll_recv(cx) } }SDK 指南的完整脉络由四个页面构成本文依次展开Rust SDK 入门工程搭建、加载模型、发送对话请求流式响应处理Response变体分类、工具调用进度事件、取消与背压嵌入 Axum 应用把 mistralrs 的 HTTP API 挂载进现有 Axum 路由Rust SDK API 参考Model完整方法面。二、工程搭建与 Cargo 依赖前置条件需要 Rust 工具链通过 rustup 安装且工程使用 tokio 异步运行时。按指南创建二进制工程cargo new --bin hello-mistralrs cd hello-mistralrs在Cargo.toml中添加依赖。默认特性构建的是 CPU 版本[dependencies] anyhow 1 mistralrs 0.8 tokio { version 1, features [full] }如需 GPU 加速按平台启用对应特性# NVIDIA GPU (CUDA) mistralrs { version 0.8, features [cuda, flash-attn, cudnn] } # Apple Silicon (Metal) mistralrs { version 0.8, features [metal] } # Intel CPU with MKL mistralrs { version 0.8, features [mkl] }这些特性名与 CLI 构建特性一一对应。注意 CUDA 场景下flash-attn、cudnn属于可选的加速增强特性纯cuda特性即可完成基础推理。三、第一个推理程序加载模型并发起对话以下是入门指南给出的最小完整示例加载 Qwen3-4B 并发送一条对话消息use anyhow::Result; use mistralrs::{IsqBits, ModelBuilder, TextMessageRole, TextMessages}; #[tokio::main] async fn main() - Result() { let model ModelBuilder::new(Qwen/Qwen3-4B) .with_auto_isq(IsqBits::Four) .with_logging() .build() .await?; let messages TextMessages::new().add_message( TextMessageRole::User, In one sentence, what is Rust known for?, ); let response model.send_chat_request(messages).await?; println!({}, response.choices[0].message.content.as_ref().unwrap()); Ok(()) }用cargo run --release运行。首次运行会把权重下载到 Hugging Face 缓存目录。3.1 ModelBuilder流式配置对象ModelBuilder是一个链式fluent配置对象每个方法返回self。唯一必填参数是传给ModelBuilder::new的 Hugging Face 仓库 id或本地路径其余全部有默认值build()负责加载权重并返回Model。从 builder_macros.rs 源码可以看到这些方法的底层形态with_isq(IsqType)builder_macros.rs L136固定指定一种量化类型with_auto_isq(IsqBits)builder_macros.rs L148由引擎按平台自动挑选最优 4-bit 格式——Metal 上选 AFQ4CUDA/CPU 上选 Q4Kwith_logging()builder_macros.rs L215启用引擎日志。with_auto_isq(IsqBits::Four)对应 CLI 的--isq 4即 ISQin-situ quantization就地量化到 4 bit去掉这一行则以未量化精度运行。若想锁定具体格式改用with_isq(IsqType::Q4K)。ISQ 的类型定义可进一步查看 isq_setting.rs。3.2 TextMessages 与 RequestBuilder 的边界TextMessages用于组装基础对话上下文适合快速上手。当你需要以下能力时应当切换到RequestBuilder逐条消息独立的采样参数工具toolschema 声明logprobs 返回结构化输出约束。Model是ModelBuilder、GgufModelBuilder、EmbeddingModelBuilder、LoraModelBuilder等所有 builder 的共同产物因此一个Model实例可以同时服务文本、GGUF、Embedding、LoRA 等多种模型形态。SDK 参考页在 docs/src/content/docs/reference/rust-sdk.md 中列出了Model的完整方法面各专用 builder 的细节见 crate 级 rustdoc 文档。四、流式响应处理 Response 变体入门指南中给出了流式输出的最小循环核心是model.stream_chat_request(messages)返回一个futures::Stream逐块消费use anyhow::Result; use futures::StreamExt; use mistralrs::{ ChatCompletionChunkResponse, ChunkChoice, Delta, IsqBits, ModelBuilder, Response, TextMessageRole, TextMessages, }; use std::io::Write; #[tokio::main] async fn main() - Result() { let model ModelBuilder::new(Qwen/Qwen3-4B) .with_auto_isq(IsqBits::Four) .build() .await?; let messages TextMessages::new().add_message( TextMessageRole::User, Write me a haiku about ownership., ); let mut stream model.stream_chat_request(messages).await?; let stdout std::io::stdout(); let mut out std::io::BufWriter::new(stdout.lock()); while let Some(item) stream.next().await { if let Response::Chunk(ChatCompletionChunkResponse { choices, .. }) item { if let Some(ChunkChoice { delta: Delta { content: Some(text), .. }, .. }) choices.first() { out.write_all(text.as_bytes())?; out.flush()?; } } } Ok(()) }从 model.rs 源码 可见stream_chat_request内部创建容量为 1 的 mpsc 通道构造一个is_streaming: true的NormalRequest交给引擎引擎每生成一个 token 就通过该通道投递一个Response。返回的Stream借用模型生命周期实现futures::StreamItem Response。4.1 Response 变体全景生产代码应当显式匹配流上的每一种Response变体。以下是 streaming 指南 给出的完整处理范式use futures::StreamExt; use mistralrs::{ChatCompletionChunkResponse, ChunkChoice, Delta, Response}; use std::io::Write; let mut stream model.stream_chat_request(messages).await?; let mut out std::io::BufWriter::new(std::io::stdout()); while let Some(item) stream.next().await { match item { Response::Chunk(ChatCompletionChunkResponse { choices, .. }) { if let Some(ChunkChoice { delta: Delta { content: Some(text), .. }, .. }) choices.first() { out.write_all(text.as_bytes())?; out.flush()?; } } Response::Done(_) break, Response::InternalError(e) { eprintln!(stream error: {e}); break; } Response::ModelError(msg, _) { eprintln!(stream error: {msg}); break; } _ {} } }聊天流上可能出现的变体及语义变体语义Response::Chunk最常见情况增量文本位于choices[0].delta.contentResponse::Done流结束携带最终的ChatCompletionResponse与用量统计Response::InternalError引擎级故障此后流不再产出任何值Response::ModelError模型级故障附带截至目前已生成的 partial responseResponse::AgenticToolCallProgress/AgenticToolApprovalRequired/File服务端工具在流中间执行时发出的事件示例中_ {}仅为简洁起见生产代码应对 agentic 变体做显式匹配。对应可运行示例位于 text_generation 入门示例、streaming 入门示例 与 error_handling 高级示例。4.2 流式场景下的工具调用事件当 agentic 循环 在流中间执行工具如 web 搜索、代码执行、shell、MCP 工具时进度事件会按流顺序与内容块交错出现use mistralrs::core::AgenticToolCallPhase; Response::AgenticToolCallProgress { round, tool_name, phase } { match phase { AgenticToolCallPhase::Calling(_) println!([round {round}: calling {tool_name}]), AgenticToolCallPhase::Complete(_) println!([round {round}: completed {tool_name}]), } }注意非流式接口send_chat_request会在内部跳过这些事件只返回最终响应需要观察工具执行过程就必须使用流式接口。4.3 任务派生、背压与取消Stream在其生命周期内借用Model因此它可以在同一作用域内跨 await 点移动但不能单独Send进 detached 任务。Model本身也不实现Clone。要在派生任务中流式生成需要用Arc共享模型、并在任务内部创建流use std::sync::Arc; let model Arc::new(model); let handle tokio::spawn({ let model Arc::clone(model); async move { let mut stream model.stream_chat_request(messages).await?; while let Some(item) stream.next().await { // forward chunks to a channel, websocket, etc. } anyhow::Ok(()) } });背压与取消语义同样清晰流背后的响应通道是有界的消费方停止 poll 就会对引擎施加背压要提前取消直接 drop 掉Stream通道随之关闭引擎对该请求的生成即告停止。4.4 边流式边收集完整响应在追求首 token 低延迟反馈的同时又想拿到完整输出用于日志或持久化可以在消费循环里同步拼接let mut full_response String::new(); while let Some(item) stream.next().await { if let Response::Chunk(chunk) item { if let Some(choice) chunk.choices.first() { if let Some(text) choice.delta.content { full_response.push_str(text); out.write_all(text.as_bytes())?; out.flush()?; } } } } // full_response now holds the complete assistant output.五、把 HTTP API 嵌入现有 Axum 应用如果既要进程内直接调用又要对外暴露 OpenAI 兼容的 HTTP 接口无需单独部署 mistralrs 服务端——可以直接把整套 API 作为子路由挂进现有 Axum 应用。这一能力由mistralrs-server-corecrate 提供核心是两个 builderMistralRsForServerBuilder构造引擎状态SharedMistralRsState ArcMistralRs后续自定义 handler 也会用到MistralRsServerRouterBuilder由该状态产出 AxumRouter。注意此场景不需要高层mistralrscrate服务端 builder 直接消费mistralrs-core的ModelSelected。5.1 依赖配置[dependencies] anyhow 1 mistralrs-core 0.8 mistralrs-server-core 0.8 axum 0.8 tokio { version 1, features [full] }5.2 挂载到子路径以下代码把 mistralrs 路由挂载到/ai子路径下use axum::{Router, routing::get}; use mistralrs_core::{AutoDeviceMapParams, ModelDType, ModelSelected}; use mistralrs_server_core::{ mistralrs_for_server_builder::MistralRsForServerBuilder, mistralrs_server_router_builder::MistralRsServerRouterBuilder, }; #[tokio::main] async fn main() - anyhow::Result() { let model ModelSelected::Plain { model_id: Qwen/Qwen3-4B.into(), tokenizer_json: None, arch: None, dtype: ModelDType::Auto, topology: None, organization: None, write_uqff: None, from_uqff: None, imatrix: None, calibration_file: None, max_seq_len: AutoDeviceMapParams::DEFAULT_MAX_SEQ_LEN, max_batch_size: AutoDeviceMapParams::DEFAULT_MAX_BATCH_SIZE, hf_cache_path: None, matformer_config_path: None, matformer_slice_name: None, }; let shared_mistralrs MistralRsForServerBuilder::new() .with_model(model) .with_in_situ_quant(4.to_string()) .build() .await?; let mistralrs_router MistralRsServerRouterBuilder::new() .with_mistralrs(shared_mistralrs) .build() .await?; let app Router::new() .route(/, get(|| async { My app })) .nest(/ai, mistralrs_router); let listener tokio::net::TcpListener::bind(0.0.0.0:3000).await?; axum::serve(listener, app).await?; Ok(()) }挂载完成后POST /ai/v1/chat/completions与独立服务端行为完全一致其余路由同样可用。with_in_situ_quant(4)对应 ISQ 4-bit 量化去掉则按未量化加载。由于ModelSelected枚举会逐个命名所有字段当 crate 新增字段时该结构体字面量将无法通过编译——这是刻意设计的安全特性迫使开发者显式处理新字段。字段的权威清单以mistralrs-server-core的 crate 级 rustdoc 为准。5.3 Builder 可选项MistralRsServerRouterBuilder暴露的配置项with_include_swagger_routes(bool)是否包含 Swagger 文档路由with_base_path(str)基础路径with_allowed_origins(VecString)CORS 允许的源with_max_body_limit(usize)请求体大小上限with_max_tool_rounds(usize)单请求最大工具轮数with_tool_dispatch_url(String)工具分发地址with_agent_permission(AgentPermission)与with_code_execution_permission(CodeExecutionPermission)agent / 代码执行的权限策略。MistralRsForServerBuilder则提供引擎级选项with_model、with_in_situ_quant、set_paged_attn、with_seed以及通过add_model支持多模型等。5.4 在自定义 handler 中直接调用模型对于自定义请求形态可以直接把SharedMistralRsState注入 Axum handler再调用mistralrs-server-core暴露的低层辅助函数如chat_completion::parse_request、handler_core::send_request完成请求解析与发送。带自定义 OpenAPI 集成的完整示例位于mistralrs-server-corecrate 级文档中。六、Model API 参考速览rust-sdk.md 罗列了Model的完整调用面。所有方法均以self接收因此可以按引用共享或放进Arc。大多数请求方法存在*_with_model(..., model_id: Optionstr)孪生版本用于多模型场景None指向默认模型。6.1 对话与生成async fn chat(self, message: impl ToString) - ResultString一次性快速对话发送单条用户消息返回助手文本回复。async fn send_chat_requestR: RequestLike(self, request: R) - ResultChatCompletionResponse非流式生成接受TextMessages、MultimodalMessages或RequestBuilder。示例见 text_generation。async fn stream_chat_requestR: RequestLike(self, request: R) - ResultStream_流式生成返回实现futures::StreamItem Response的Stream借用模型。完整指南见 streaming.md。async fn send_raw_chat_requestR: RequestLike(self, request: R) - Result(VecTensor, Vecu32)返回首个生成 token 的原始 logits 及提示词 token用于困惑度等自定义评估。示例见 perplexity。6.2 推理强度控制ReasoningEffortReasoningEffort::{Off, Low, Medium, High, XHigh}可传入TextMessages::with_reasoning_effort、MultimodalMessages::with_reasoning_effort、RequestBuilder::with_reasoning_effort与AgentBuilder::with_reasoning_effort。原有的enable_thinking(bool)/with_enable_thinking(bool)依旧可用。省略 effort 时保持 thinking 开启但级别未指定若同时给出相互矛盾的显式控制会返回请求校验错误let messages TextMessages::new() .add_message(TextMessageRole::User, Solve this carefully.) .with_reasoning_effort(ReasoningEffort::High);注意effort 会被传给模型的 chat template不会直接改动采样参数。这一校验逻辑在 model.rs 的 validate_reasoning_controls 中实现。6.3 结构化输出async fn generate_structuredT(self, messages: impl IntoRequestBuilder) - ResultT where T: DeserializeOwned JsonSchema基于T的 JSON Schema经schemars推导约束生成过程随后把回复反序列化为T。示例见 structured。6.4 Agentic 工具先在模型 builder 上启用内置执行器再按请求逐个启用let model ModelBuilder::new(Qwen/Qwen3-4B) .with_code_execution(CodeExecutionConfig::default()) .with_shell_execution(ShellConfig::default()) .build() .await?; let req RequestBuilder::from(messages) .with_code_execution() .with_shell_skill(my-skill, Local task-specific skill., skills/my-skill) .with_max_tool_rounds(6);with_input_file(InputFile::from_text(...))用于附加用户提供的请求文件with_shell_execution()为请求启用纯 shellwith_shell_skill(...)以与 OpenAI 兼容 Skills 相同的目录结构挂载本地技能目录。对应示例file_inputs、code_execution、shell、shell_skills。6.5 Embeddings、图像与语音async fn generate_embeddings(self, request: EmbeddingRequestBuilder) - ResultVecVecf32按输入顺序为每个输入返回一条 embedding 向量。示例见 embeddings。async fn generate_embedding(self, prompt: impl ToString) - ResultVecf32单输入便捷封装。async fn generate_image(self, prompt: impl ToString, response_format: ImageGenerationResponseFormat, generation_params: DiffusionGenerationParams, save_file: OptionPathBuf) - ResultImageGenerationResponse扩散模型文生图。示例见 diffusion。async fn generate_speech(self, prompt: impl ToString) - Result(ArcVecf32, usize, usize)文本转语音返回(pcm, sample_rate, channels)。示例见 speech。6.6 量化与在线校准async fn re_isq_model(self, isq_type: IsqType) - Result()对已加载模型就地重新应用 ISQ目标设备保持不变。在线校准三件套模型必须以 ISQ 方式加载async fn begin_calibration(self) - ResultCalibrationStatus async fn calibration_status(self) - ResultCalibrationStatus async fn apply_calibration(self, save_cimatrix: OptionPathBuf) - ResultCalibrationStatusbegin_calibration开始从实时流量收集激活统计calibration_status报告逐层进度apply_calibration从源权重重新量化并热切换层save_cimatrix可选地把重要性矩阵写入.cimatrix文件以供复用。对应示例见 online_calibration。6.7 分词与工具调用async fn tokenize(self, text: EitherTextMessages, String, tools: OptionVecTool, add_special_tokens: bool, add_generation_prompt: bool, enable_thinking: Optionbool) - ResultVecu32对原始文本或聊天消息分词——消息会经过 chat templatetools仅对消息形态生效。async fn tokenize_with_reasoning_effort(self, text: EitherTextMessages, String, tools: OptionVecTool, add_special_tokens: bool, add_generation_prompt: bool, enable_thinking: Optionbool, reasoning_effort: OptionReasoningEffort) - ResultVecu32当分词需要体现显式 effort 时使用该变体原始字符串直接分词不渲染 chat template。async fn detokenize(self, tokens: Vecu32, skip_special_tokens: bool) - ResultString6.8 内省与管理config() - ResultMistralRsConfig返回已加载模型的模态与设备信息max_sequence_length() - ResultOptionusize多模型list_models、add_model、remove_model、unload_model、reload_model、get_default_model_id、set_default_model_id、list_models_with_status示例见 multi_model会话export_session、import_session、delete_session、fork_session、list_session_idslist_mcp_tools(model_id)返回某模型已注册的 MCP 工具以(name, description)对呈现find_file(id)按 id 获取 agentic 运行时产出的文件完整内容inner() - MistralRs对底层引擎的逃生通道Model::new(ArcMistralRs)则可将引擎实例重新包装为Model。七、性能与并发注意事项入门指南的 Notes 部分给出了三条关键工程约束均可在 model.rs 源码 中得到印证build()是重操作。ModelBuilder::build()执行完整的模型加载流程开销很大应当在启动阶段只调用一次。Model方法取self可安全并发调用。一个实例可以通过引用共享给多个调用方需要移入派生任务时用ArcModel包装Model不实现Clone。请求绕过 HTTP 层。Rust SDK 请求不经过/v1/chat/completions也不存在 OpenAI 兼容 shim既要进程内直接访问、又要对外暴露 HTTP 时走 embed-in-axum 方案 将 API 作为子路由挂载是最省事的一条路径。结语从 Rust SDK 索引页 出发本文完整覆盖了 mistral.rs Rust SDK 的入门、流式、Axum 嵌入与 API 参考四个层面。整体设计思路很清晰ModelBuilder负责昂贵的加载阶段并产出可安全并发共享的ModelModel以统一的Response枚举贯通非流式、流式与工具事件mistralrs-server-core则把同一引擎复用到 HTTP 场景。无论你是要在 CLI 工具中内嵌推理、构建实时流式 Agent还是把 mistralrs 的能力无缝并入现有 Web 服务这套 SDK 都提供了最小成本的接入方式。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mistral.rs Rust SDK 实战：将 LLM 推理引擎内嵌进 Rust 程序
mistral.rs Rust SDK 实战将 LLM 推理引擎内嵌进 Rust 程序【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsmistralrscrate 将 mistral.rs 的推理引擎直接嵌入到 Rust 进程中让你在无需启动独立 HTTP 服务的前提下于进程内加载模型、发送对话请求并消费流式输出。本文以 Rust SDK 指南 为核心骨架结合 SDK 参考 与 Model 实现源码系统讲解从工程搭建、首次推理、流式响应处理到把整套 HTTP API 挂载进现有 Axum 应用的完整路径。读完本文你将掌握ModelBuilder/Model的完整调用面、Response流式变体处理范式以及mistralrs-server-core两个关键 builder 的嵌入用法。一、Rust SDK 是什么Rust SDK 的核心价值是“进程内推理”不需要/v1/chat/completions端点也没有 OpenAI 兼容层请求直接走 Rust 内部通道。这一点从 Model 源码 可以印证——Model结构内部仅持有一个ArcMistralRs引擎句柄而Streama则是对tokio::sync::mpsc::ReceiverResponse的封装并通过实现futures::Streamtrait 对外提供poll_next能力pub struct Streama { _server: a Model, rx: ReceiverResponse, } impl futures::Stream for Stream_ { type Item Response; fn poll_next(mut self: Pinmut Self, cx: mut TaskContext_) - PollOptionSelf::Item { self.rx.poll_recv(cx) } }SDK 指南的完整脉络由四个页面构成本文依次展开Rust SDK 入门工程搭建、加载模型、发送对话请求流式响应处理Response变体分类、工具调用进度事件、取消与背压嵌入 Axum 应用把 mistralrs 的 HTTP API 挂载进现有 Axum 路由Rust SDK API 参考Model完整方法面。二、工程搭建与 Cargo 依赖前置条件需要 Rust 工具链通过 rustup 安装且工程使用 tokio 异步运行时。按指南创建二进制工程cargo new --bin hello-mistralrs cd hello-mistralrs在Cargo.toml中添加依赖。默认特性构建的是 CPU 版本[dependencies] anyhow 1 mistralrs 0.8 tokio { version 1, features [full] }如需 GPU 加速按平台启用对应特性# NVIDIA GPU (CUDA) mistralrs { version 0.8, features [cuda, flash-attn, cudnn] } # Apple Silicon (Metal) mistralrs { version 0.8, features [metal] } # Intel CPU with MKL mistralrs { version 0.8, features [mkl] }这些特性名与 CLI 构建特性一一对应。注意 CUDA 场景下flash-attn、cudnn属于可选的加速增强特性纯cuda特性即可完成基础推理。三、第一个推理程序加载模型并发起对话以下是入门指南给出的最小完整示例加载 Qwen3-4B 并发送一条对话消息use anyhow::Result; use mistralrs::{IsqBits, ModelBuilder, TextMessageRole, TextMessages}; #[tokio::main] async fn main() - Result() { let model ModelBuilder::new(Qwen/Qwen3-4B) .with_auto_isq(IsqBits::Four) .with_logging() .build() .await?; let messages TextMessages::new().add_message( TextMessageRole::User, In one sentence, what is Rust known for?, ); let response model.send_chat_request(messages).await?; println!({}, response.choices[0].message.content.as_ref().unwrap()); Ok(()) }用cargo run --release运行。首次运行会把权重下载到 Hugging Face 缓存目录。3.1 ModelBuilder流式配置对象ModelBuilder是一个链式fluent配置对象每个方法返回self。唯一必填参数是传给ModelBuilder::new的 Hugging Face 仓库 id或本地路径其余全部有默认值build()负责加载权重并返回Model。从 builder_macros.rs 源码可以看到这些方法的底层形态with_isq(IsqType)builder_macros.rs L136固定指定一种量化类型with_auto_isq(IsqBits)builder_macros.rs L148由引擎按平台自动挑选最优 4-bit 格式——Metal 上选 AFQ4CUDA/CPU 上选 Q4Kwith_logging()builder_macros.rs L215启用引擎日志。with_auto_isq(IsqBits::Four)对应 CLI 的--isq 4即 ISQin-situ quantization就地量化到 4 bit去掉这一行则以未量化精度运行。若想锁定具体格式改用with_isq(IsqType::Q4K)。ISQ 的类型定义可进一步查看 isq_setting.rs。3.2 TextMessages 与 RequestBuilder 的边界TextMessages用于组装基础对话上下文适合快速上手。当你需要以下能力时应当切换到RequestBuilder逐条消息独立的采样参数工具toolschema 声明logprobs 返回结构化输出约束。Model是ModelBuilder、GgufModelBuilder、EmbeddingModelBuilder、LoraModelBuilder等所有 builder 的共同产物因此一个Model实例可以同时服务文本、GGUF、Embedding、LoRA 等多种模型形态。SDK 参考页在 docs/src/content/docs/reference/rust-sdk.md 中列出了Model的完整方法面各专用 builder 的细节见 crate 级 rustdoc 文档。四、流式响应处理 Response 变体入门指南中给出了流式输出的最小循环核心是model.stream_chat_request(messages)返回一个futures::Stream逐块消费use anyhow::Result; use futures::StreamExt; use mistralrs::{ ChatCompletionChunkResponse, ChunkChoice, Delta, IsqBits, ModelBuilder, Response, TextMessageRole, TextMessages, }; use std::io::Write; #[tokio::main] async fn main() - Result() { let model ModelBuilder::new(Qwen/Qwen3-4B) .with_auto_isq(IsqBits::Four) .build() .await?; let messages TextMessages::new().add_message( TextMessageRole::User, Write me a haiku about ownership., ); let mut stream model.stream_chat_request(messages).await?; let stdout std::io::stdout(); let mut out std::io::BufWriter::new(stdout.lock()); while let Some(item) stream.next().await { if let Response::Chunk(ChatCompletionChunkResponse { choices, .. }) item { if let Some(ChunkChoice { delta: Delta { content: Some(text), .. }, .. }) choices.first() { out.write_all(text.as_bytes())?; out.flush()?; } } } Ok(()) }从 model.rs 源码 可见stream_chat_request内部创建容量为 1 的 mpsc 通道构造一个is_streaming: true的NormalRequest交给引擎引擎每生成一个 token 就通过该通道投递一个Response。返回的Stream借用模型生命周期实现futures::StreamItem Response。4.1 Response 变体全景生产代码应当显式匹配流上的每一种Response变体。以下是 streaming 指南 给出的完整处理范式use futures::StreamExt; use mistralrs::{ChatCompletionChunkResponse, ChunkChoice, Delta, Response}; use std::io::Write; let mut stream model.stream_chat_request(messages).await?; let mut out std::io::BufWriter::new(std::io::stdout()); while let Some(item) stream.next().await { match item { Response::Chunk(ChatCompletionChunkResponse { choices, .. }) { if let Some(ChunkChoice { delta: Delta { content: Some(text), .. }, .. }) choices.first() { out.write_all(text.as_bytes())?; out.flush()?; } } Response::Done(_) break, Response::InternalError(e) { eprintln!(stream error: {e}); break; } Response::ModelError(msg, _) { eprintln!(stream error: {msg}); break; } _ {} } }聊天流上可能出现的变体及语义变体语义Response::Chunk最常见情况增量文本位于choices[0].delta.contentResponse::Done流结束携带最终的ChatCompletionResponse与用量统计Response::InternalError引擎级故障此后流不再产出任何值Response::ModelError模型级故障附带截至目前已生成的 partial responseResponse::AgenticToolCallProgress/AgenticToolApprovalRequired/File服务端工具在流中间执行时发出的事件示例中_ {}仅为简洁起见生产代码应对 agentic 变体做显式匹配。对应可运行示例位于 text_generation 入门示例、streaming 入门示例 与 error_handling 高级示例。4.2 流式场景下的工具调用事件当 agentic 循环 在流中间执行工具如 web 搜索、代码执行、shell、MCP 工具时进度事件会按流顺序与内容块交错出现use mistralrs::core::AgenticToolCallPhase; Response::AgenticToolCallProgress { round, tool_name, phase } { match phase { AgenticToolCallPhase::Calling(_) println!([round {round}: calling {tool_name}]), AgenticToolCallPhase::Complete(_) println!([round {round}: completed {tool_name}]), } }注意非流式接口send_chat_request会在内部跳过这些事件只返回最终响应需要观察工具执行过程就必须使用流式接口。4.3 任务派生、背压与取消Stream在其生命周期内借用Model因此它可以在同一作用域内跨 await 点移动但不能单独Send进 detached 任务。Model本身也不实现Clone。要在派生任务中流式生成需要用Arc共享模型、并在任务内部创建流use std::sync::Arc; let model Arc::new(model); let handle tokio::spawn({ let model Arc::clone(model); async move { let mut stream model.stream_chat_request(messages).await?; while let Some(item) stream.next().await { // forward chunks to a channel, websocket, etc. } anyhow::Ok(()) } });背压与取消语义同样清晰流背后的响应通道是有界的消费方停止 poll 就会对引擎施加背压要提前取消直接 drop 掉Stream通道随之关闭引擎对该请求的生成即告停止。4.4 边流式边收集完整响应在追求首 token 低延迟反馈的同时又想拿到完整输出用于日志或持久化可以在消费循环里同步拼接let mut full_response String::new(); while let Some(item) stream.next().await { if let Response::Chunk(chunk) item { if let Some(choice) chunk.choices.first() { if let Some(text) choice.delta.content { full_response.push_str(text); out.write_all(text.as_bytes())?; out.flush()?; } } } } // full_response now holds the complete assistant output.五、把 HTTP API 嵌入现有 Axum 应用如果既要进程内直接调用又要对外暴露 OpenAI 兼容的 HTTP 接口无需单独部署 mistralrs 服务端——可以直接把整套 API 作为子路由挂进现有 Axum 应用。这一能力由mistralrs-server-corecrate 提供核心是两个 builderMistralRsForServerBuilder构造引擎状态SharedMistralRsState ArcMistralRs后续自定义 handler 也会用到MistralRsServerRouterBuilder由该状态产出 AxumRouter。注意此场景不需要高层mistralrscrate服务端 builder 直接消费mistralrs-core的ModelSelected。5.1 依赖配置[dependencies] anyhow 1 mistralrs-core 0.8 mistralrs-server-core 0.8 axum 0.8 tokio { version 1, features [full] }5.2 挂载到子路径以下代码把 mistralrs 路由挂载到/ai子路径下use axum::{Router, routing::get}; use mistralrs_core::{AutoDeviceMapParams, ModelDType, ModelSelected}; use mistralrs_server_core::{ mistralrs_for_server_builder::MistralRsForServerBuilder, mistralrs_server_router_builder::MistralRsServerRouterBuilder, }; #[tokio::main] async fn main() - anyhow::Result() { let model ModelSelected::Plain { model_id: Qwen/Qwen3-4B.into(), tokenizer_json: None, arch: None, dtype: ModelDType::Auto, topology: None, organization: None, write_uqff: None, from_uqff: None, imatrix: None, calibration_file: None, max_seq_len: AutoDeviceMapParams::DEFAULT_MAX_SEQ_LEN, max_batch_size: AutoDeviceMapParams::DEFAULT_MAX_BATCH_SIZE, hf_cache_path: None, matformer_config_path: None, matformer_slice_name: None, }; let shared_mistralrs MistralRsForServerBuilder::new() .with_model(model) .with_in_situ_quant(4.to_string()) .build() .await?; let mistralrs_router MistralRsServerRouterBuilder::new() .with_mistralrs(shared_mistralrs) .build() .await?; let app Router::new() .route(/, get(|| async { My app })) .nest(/ai, mistralrs_router); let listener tokio::net::TcpListener::bind(0.0.0.0:3000).await?; axum::serve(listener, app).await?; Ok(()) }挂载完成后POST /ai/v1/chat/completions与独立服务端行为完全一致其余路由同样可用。with_in_situ_quant(4)对应 ISQ 4-bit 量化去掉则按未量化加载。由于ModelSelected枚举会逐个命名所有字段当 crate 新增字段时该结构体字面量将无法通过编译——这是刻意设计的安全特性迫使开发者显式处理新字段。字段的权威清单以mistralrs-server-core的 crate 级 rustdoc 为准。5.3 Builder 可选项MistralRsServerRouterBuilder暴露的配置项with_include_swagger_routes(bool)是否包含 Swagger 文档路由with_base_path(str)基础路径with_allowed_origins(VecString)CORS 允许的源with_max_body_limit(usize)请求体大小上限with_max_tool_rounds(usize)单请求最大工具轮数with_tool_dispatch_url(String)工具分发地址with_agent_permission(AgentPermission)与with_code_execution_permission(CodeExecutionPermission)agent / 代码执行的权限策略。MistralRsForServerBuilder则提供引擎级选项with_model、with_in_situ_quant、set_paged_attn、with_seed以及通过add_model支持多模型等。5.4 在自定义 handler 中直接调用模型对于自定义请求形态可以直接把SharedMistralRsState注入 Axum handler再调用mistralrs-server-core暴露的低层辅助函数如chat_completion::parse_request、handler_core::send_request完成请求解析与发送。带自定义 OpenAPI 集成的完整示例位于mistralrs-server-corecrate 级文档中。六、Model API 参考速览rust-sdk.md 罗列了Model的完整调用面。所有方法均以self接收因此可以按引用共享或放进Arc。大多数请求方法存在*_with_model(..., model_id: Optionstr)孪生版本用于多模型场景None指向默认模型。6.1 对话与生成async fn chat(self, message: impl ToString) - ResultString一次性快速对话发送单条用户消息返回助手文本回复。async fn send_chat_requestR: RequestLike(self, request: R) - ResultChatCompletionResponse非流式生成接受TextMessages、MultimodalMessages或RequestBuilder。示例见 text_generation。async fn stream_chat_requestR: RequestLike(self, request: R) - ResultStream_流式生成返回实现futures::StreamItem Response的Stream借用模型。完整指南见 streaming.md。async fn send_raw_chat_requestR: RequestLike(self, request: R) - Result(VecTensor, Vecu32)返回首个生成 token 的原始 logits 及提示词 token用于困惑度等自定义评估。示例见 perplexity。6.2 推理强度控制ReasoningEffortReasoningEffort::{Off, Low, Medium, High, XHigh}可传入TextMessages::with_reasoning_effort、MultimodalMessages::with_reasoning_effort、RequestBuilder::with_reasoning_effort与AgentBuilder::with_reasoning_effort。原有的enable_thinking(bool)/with_enable_thinking(bool)依旧可用。省略 effort 时保持 thinking 开启但级别未指定若同时给出相互矛盾的显式控制会返回请求校验错误let messages TextMessages::new() .add_message(TextMessageRole::User, Solve this carefully.) .with_reasoning_effort(ReasoningEffort::High);注意effort 会被传给模型的 chat template不会直接改动采样参数。这一校验逻辑在 model.rs 的 validate_reasoning_controls 中实现。6.3 结构化输出async fn generate_structuredT(self, messages: impl IntoRequestBuilder) - ResultT where T: DeserializeOwned JsonSchema基于T的 JSON Schema经schemars推导约束生成过程随后把回复反序列化为T。示例见 structured。6.4 Agentic 工具先在模型 builder 上启用内置执行器再按请求逐个启用let model ModelBuilder::new(Qwen/Qwen3-4B) .with_code_execution(CodeExecutionConfig::default()) .with_shell_execution(ShellConfig::default()) .build() .await?; let req RequestBuilder::from(messages) .with_code_execution() .with_shell_skill(my-skill, Local task-specific skill., skills/my-skill) .with_max_tool_rounds(6);with_input_file(InputFile::from_text(...))用于附加用户提供的请求文件with_shell_execution()为请求启用纯 shellwith_shell_skill(...)以与 OpenAI 兼容 Skills 相同的目录结构挂载本地技能目录。对应示例file_inputs、code_execution、shell、shell_skills。6.5 Embeddings、图像与语音async fn generate_embeddings(self, request: EmbeddingRequestBuilder) - ResultVecVecf32按输入顺序为每个输入返回一条 embedding 向量。示例见 embeddings。async fn generate_embedding(self, prompt: impl ToString) - ResultVecf32单输入便捷封装。async fn generate_image(self, prompt: impl ToString, response_format: ImageGenerationResponseFormat, generation_params: DiffusionGenerationParams, save_file: OptionPathBuf) - ResultImageGenerationResponse扩散模型文生图。示例见 diffusion。async fn generate_speech(self, prompt: impl ToString) - Result(ArcVecf32, usize, usize)文本转语音返回(pcm, sample_rate, channels)。示例见 speech。6.6 量化与在线校准async fn re_isq_model(self, isq_type: IsqType) - Result()对已加载模型就地重新应用 ISQ目标设备保持不变。在线校准三件套模型必须以 ISQ 方式加载async fn begin_calibration(self) - ResultCalibrationStatus async fn calibration_status(self) - ResultCalibrationStatus async fn apply_calibration(self, save_cimatrix: OptionPathBuf) - ResultCalibrationStatusbegin_calibration开始从实时流量收集激活统计calibration_status报告逐层进度apply_calibration从源权重重新量化并热切换层save_cimatrix可选地把重要性矩阵写入.cimatrix文件以供复用。对应示例见 online_calibration。6.7 分词与工具调用async fn tokenize(self, text: EitherTextMessages, String, tools: OptionVecTool, add_special_tokens: bool, add_generation_prompt: bool, enable_thinking: Optionbool) - ResultVecu32对原始文本或聊天消息分词——消息会经过 chat templatetools仅对消息形态生效。async fn tokenize_with_reasoning_effort(self, text: EitherTextMessages, String, tools: OptionVecTool, add_special_tokens: bool, add_generation_prompt: bool, enable_thinking: Optionbool, reasoning_effort: OptionReasoningEffort) - ResultVecu32当分词需要体现显式 effort 时使用该变体原始字符串直接分词不渲染 chat template。async fn detokenize(self, tokens: Vecu32, skip_special_tokens: bool) - ResultString6.8 内省与管理config() - ResultMistralRsConfig返回已加载模型的模态与设备信息max_sequence_length() - ResultOptionusize多模型list_models、add_model、remove_model、unload_model、reload_model、get_default_model_id、set_default_model_id、list_models_with_status示例见 multi_model会话export_session、import_session、delete_session、fork_session、list_session_idslist_mcp_tools(model_id)返回某模型已注册的 MCP 工具以(name, description)对呈现find_file(id)按 id 获取 agentic 运行时产出的文件完整内容inner() - MistralRs对底层引擎的逃生通道Model::new(ArcMistralRs)则可将引擎实例重新包装为Model。七、性能与并发注意事项入门指南的 Notes 部分给出了三条关键工程约束均可在 model.rs 源码 中得到印证build()是重操作。ModelBuilder::build()执行完整的模型加载流程开销很大应当在启动阶段只调用一次。Model方法取self可安全并发调用。一个实例可以通过引用共享给多个调用方需要移入派生任务时用ArcModel包装Model不实现Clone。请求绕过 HTTP 层。Rust SDK 请求不经过/v1/chat/completions也不存在 OpenAI 兼容 shim既要进程内直接访问、又要对外暴露 HTTP 时走 embed-in-axum 方案 将 API 作为子路由挂载是最省事的一条路径。结语从 Rust SDK 索引页 出发本文完整覆盖了 mistral.rs Rust SDK 的入门、流式、Axum 嵌入与 API 参考四个层面。整体设计思路很清晰ModelBuilder负责昂贵的加载阶段并产出可安全并发共享的ModelModel以统一的Response枚举贯通非流式、流式与工具事件mistralrs-server-core则把同一引擎复用到 HTTP 场景。无论你是要在 CLI 工具中内嵌推理、构建实时流式 Agent还是把 mistralrs 的能力无缝并入现有 Web 服务这套 SDK 都提供了最小成本的接入方式。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考