mistral.rs Python SDK 请求数据类完全指南ChatCompletionRequest、CompletionRequest 与 EmbeddingRequest 详解【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本篇指南围绕 mistral.rs 官方 Python 参考文档 Requests 展开系统讲解传给Runner方法的三个核心请求数据类ChatCompletionRequest、CompletionRequest、EmbeddingRequest以及用于精确选定 LoRA 适配器版本的LoraAdapterGeneration。读完本文你将掌握每个字段的类型、默认值与底层行为学会配置采样参数、结构化输出约束、推理开关、工具调用与 Agent 权限、文件输入输出以及动态 LoRA 路由并能在真实场景中直接编写可运行的请求代码。请求数据类概述在 mistral.rs 的 Python 包mistralrs-pyo3类型声明见 mistralrs.pyi中所有请求都以数据类dataclass形式暴露分别对应引擎的三类核心能力请求类对应Runner方法用途ChatCompletionRequestsend_chat_completion_request对话补全支持消息列表、工具调用、Agent 动作、文件与流式输出CompletionRequestsend_completion_request原始文本补全直接给定一段 prompt 前缀续写EmbeddingRequestsend_embedding_request为输入文本或 token 序列计算嵌入向量这些数据类在 Rust 侧的对应实现在 requests.rs其中的 PyO3#[pyclass]与#[pymethods]定义了 Python 侧的构造签名、类型校验与字段解析逻辑。每个请求都携带model字段在多模型模式下用于指定目标模型 ID单模型场景下通常填default也可以不填让Runner使用默认模型。ChatCompletionRequest对话补全的请求载体ChatCompletionRequest表示发送给 mistral.rs 引擎的一次对话补全请求编码了输入数据、采样参数以及响应返回方式等信息。messages三种输入形态messages是唯一必填的输入字段model同样必填其类型为messages: list[dict[str, str]] | list[dict[str, list[dict[str, str | dict[str, str]]]]] | str它支持三种形态普通对话消息list[dict[str, str]]即{role: ..., content: ...}列表是最常用的形态带图片等多模态内容的对话消息list[dict[str, list[dict[str, str | dict[str, str]]]]]用于聊天补全携带图像以及语音、视频输入的场景预模板化 prompt直接传str此时 mistral.rs 不会套用对话模板而是把该字符串当作已经渲染好的提示词直接送入引擎。从源码看requests.rs 在构造时通过downcast_exact::PyList()与downcast_exact::PyString()精确区分列表与字符串两种输入若不是这两种类型则抛出TypeError(Expected a string or list of dicts.)。完整字段表以下是ChatCompletionRequest的全部字段与原文档一致并补充了便于实操的说明字段类型默认值messageslist[dict[str, str]] \| list[dict[str, list[dict[str, str \| dict[str, str]]]]] \| str必填modelstr必填logprobsboolFalsen_choicesint1logit_biasdict[int, float] \| NoneNonetop_logprobsint \| NoneNonemax_tokensint \| NoneNonepresence_penaltyfloat \| NoneNonefrequency_penaltyfloat \| NoneNonerepetition_penaltyfloat \| NoneNonestop_seqslist[str] \| NoneNonetemperaturefloat \| NoneNonetop_pfloat \| NoneNonetop_kint \| NoneNonestreamboolFalsegrammarstr \| NoneNonegrammar_typestr \| NoneNonemin_pfloat \| NoneNonetool_schemaslist[str] \| NoneNonetool_choiceToolChoice \| NoneNonedry_multiplierfloat \| NoneNonedry_basefloat \| NoneNonedry_allowed_lengthint \| NoneNonedry_sequence_breakerslist[str] \| NoneNoneweb_search_optionsWebSearchOptions \| NoneNoneenable_thinkingbool \| NoneNonetruncate_sequenceboolFalsereasoning_effortLiteral[off, none, low, medium, high, xhigh] \| NoneNonemax_tool_roundsint \| NoneNonetool_dispatch_urlstr \| NoneNoneenable_code_executionboolFalseenable_shellboolFalseshell_skillslist[ShellSkillMount] \| NoneNoneagent_permissionAgentPermission \| NoneNoneagent_approval_callbackCallable[[AgentToolApproval], bool \| AgentToolApprovalDecision] \| NoneNonecode_execution_permissionCodeExecutionPermission \| NoneNonesession_idstr \| NoneNonefileslist[RequestedFile] \| NoneNoneinput_fileslist[InputFile] \| NoneNoneignore_eosboolFalseadapterstr \| LoraAdapterGeneration \| NoneNone仅限关键字参数采样参数说明temperature温度、top_p核采样、top_k前 k 采样、min_p最小概率采样共同控制生成随机性与多样性均为可选值不设置时使用模型默认采样策略presence_penalty/frequency_penalty/repetition_penalty三种惩罚系数用于抑制重复logit_bias以{token_id: 偏差值}形式直接调整指定 token 的采样分数n_choices控制一次返回多少个独立候补beam 之外的多次采样max_tokens限制生成长度stop_seqs提供停止词列表ignore_eosTrue时不把 EOS 当作结束标记常用于强制续写或结构化抽取logprobsTrue时开启对数概率返回配合top_logprobs可拿到每个位置的前 N 个候选 token 的概率分布streamTrue时send_chat_completion_request返回一个生成器逐块产出ChatCompletionChunkResponse见 responses.md。结构化输出grammar 与 grammar_typegrammar与grammar_type配合使用用于约束解码过程保证输出符合指定格式。grammar_type取值包括regex、json_schema、llguidance等。仓库中提供了多个可直接运行的示例正则约束regex.py 用grammar_typeregex, grammarr[0-9A-Z ]强制输出只含大写字母、数字与空格JSON Schema 约束json_schema.py 以 JSON 字符串形式传入 schema含字段类型、pattern、minimum/maximum、required等约束llguidance 约束llguidance.py 使用 LARK 文法与内联 JSON schema 组合grammar_typellguidance。在引擎侧约束最终会转换为Constraint::Regex/Constraint::JsonSchema/Constraint::Llguidance等变体见 request.rs由采样器在每一步解码时强制执行。推理控制enable_thinking 与 reasoning_effortreasoning_effort用于配置推理模型的思考强度接受off、low、medium、high、xhigh五个取值其中none是off的别名。解析时值会被trim并做大小写不敏感处理。enable_thinking是一个独立的布尔开关。两条规则需要特别注意原文档明确说明如果两个推理控制字段都省略则默认开启思考DEFAULT_ENABLE_THINKING true但不指定具体 effort 级别如果enable_thinking与reasoning_effort取值相互矛盾构造函数会抛出ValueError例如enable_thinkingTrue搭配reasoning_effortoff或enable_thinkingFalse搭配reasoning_efforthigh。从源码看这一逻辑在 request.rs 的resolve_reasoning_controls中实现(Some(true), Some(Off))报OffWithThinkingEnabled(Some(false), Some(非 off 值))报EffortWithThinkingDisabledeffort 的解析FromStr在 request.rstrim().to_ascii_lowercase()后映射同时把max也作为xhigh的别名pyi 类型标注只列出off/none/low/medium/high/xhigh。Python 侧在 requests.rs 先解析 effort 再调用resolve_reasoning_controls做一致性校验错误以ValueError形式抛给调用方。工具调用与 Agent 权限字段这是ChatCompletionRequest区别于CompletionRequest的核心能力tool_schemas工具定义的 JSON 字符串列表OpenAI 兼容格式tool_choiceToolChoice.NoTools或ToolChoice.Auto控制是否允许模型发起工具调用枚举定义见 enums.mdmax_tool_rounds引擎自动执行工具调用的最大轮数。配合Runner(tool_callbacks...)注册的 Python 回调或tool_dispatch_url指定的外部 HTTP 端点引擎会在模型-工具之间自动循环执行并回填结果完整示例见 agentic_tools.pyenable_code_execution/enable_shell/shell_skills启用内置 Python 执行器与 Shell 工具。enable_code_execution要求Runner以code_execution_config构建enable_shell要求以shell_config构建。源码中还有一个细节只要shell_skills非空enable_shell会被自动置为True见 requests.rssession_id持久化 Agent 会话的 ID跨请求保留工具执行上下文。agent_permission字段作用于所有由服务端执行的 Agent 动作——包括代码执行、Shell、Web 搜索、文件工具、回调以及外部工具分发取值为AgentPermission.Auto、.Ask或.Denyauto工具调用合法时立即执行ask执行前暂停通过agent_approval_callback请求审批deny工具对模型保持可见但直接返回被拒绝的工具结果而不真正执行。agent_approval_callback在agent_permissionAgentPermission.Ask时被调用入参是一个AgentToolApproval包含approval_id、session_id、round、tool元数据、arguments_json、code等字段回调可以返回True/False也可以返回AgentToolApprovalDecision通过AgentToolApprovalDecision.approve(remember_for_session...)或.deny(message...)构造用于携带拒绝消息与本会话记住语义详见 agent-approvals.md。一个包含人工审批的完整示例见 code_execution_approval.py。此外code_execution_permission是仅针对代码执行的兼容性别名底层会把它的值合并进agent_permission见 requests.rs新代码推荐统一使用agent_permission。共享的 CLI / HTTP / Python / Rust 权限语义可参考 permissions-and-approvals.mdx。文件字段与 Web 搜索files声明请求要求模型产出的输出文件RequestedFile(name, format, description)。运行时把声明告知模型若工具实际产出该文件会出现在ChatCompletionResponse.files中缺失时以错误占位符呈现input_files用户随请求附加的输入文件InputFile。文本类文件会在提示词上下文中预览并可由内置文件工具分页读取二进制文件则挂载到 shell/代码工作目录在提示词上下文中仅保留元数据详见 files.mdweb_search_optionsWebSearchOptions对象用于配置内置 Web 搜索工具search_context_size、user_location、search_description、extract_description。要使用该功能Runner需以enable_searchTrue构建示例见 web_search.py类型定义见 search.md。adapter 字段adapter是ChatCompletionRequest中唯一标注为仅限关键字参数keyword-only的字段用于在请求级路由 LoRA 适配器接受两种取值字符串别名alias选择当前加载到该别名下的最新适配器代generationLoraAdapterGeneration对象锁定某一个不可变的精确 generation。在 requests.rs 的parse_adapter_selection中先尝试把值解析为字符串别名再尝试解析为LoraAdapterGeneration都不是则抛出TypeError。请求完成后响应中的adapter_generation字段会回显实际使用的 generation示例见 lora.py。CompletionRequest原始文本补全CompletionRequest表示发送给引擎的一次原始补全请求直接给定一段文本 prompt 让模型续写不经过对话模板。其完整字段如下字段类型默认值promptstr必填modelstr必填best_ofint1echo_promptboolFalsepresence_penaltyfloat \| NoneNonefrequency_penaltyfloat \| NoneNonerepetition_penaltyfloat \| NoneNonelogit_biasdict[int, float] \| NoneNonemax_tokensint \| NoneNonen_choicesint1stop_seqslist[str] \| NoneNonetemperaturefloat \| NoneNonetop_pfloat \| NoneNonesuffixstr \| NoneNonetop_kint \| NoneNonegrammarstr \| NoneNonegrammar_typestr \| NoneNonemin_pfloat \| NoneNonetool_schemaslist[str] \| NoneNonetool_choiceToolChoice \| NoneNonedry_multiplierfloat \| NoneNonedry_basefloat \| NoneNonedry_allowed_lengthint \| NoneNonedry_sequence_breakerslist[str] \| NoneNonetruncate_sequenceboolFalseignore_eosboolFalseadapterstr \| LoraAdapterGeneration \| NoneNone仅限关键字参数与ChatCompletionRequest相比它用prompt取代messages多出best_of并行生成若干候选并取最优与echo_prompt回显输入 prompt并额外支持suffix——模型生成的内容会填充在prompt与suffix之间适合做填空式补全。其余采样、约束grammar/grammar_type/min_p、DRY 采样dry_multiplier/dry_base/dry_allowed_length/dry_sequence_breakers与adapter路由的语义与对话请求一致。其响应类型为CompletionResponse含CompletionChoice.text详见 responses.md。EmbeddingRequest嵌入向量计算EmbeddingRequest表示一次嵌入计算请求字段最少字段类型默认值inputstr \| list[str] \| list[int] \| list[list[int]]必填truncate_sequenceboolFalseinput的四种形态在 requests.rs 的normalize_embedding_inputs中被规范化单个字符串按单个 prompt 处理list[str]批量 prompt列表中元素个数即返回的向量条数list[int]单条 token 序列token ID 列表list[list[int]]批量 token 序列。该函数还会做两类校验空的字符串列表或 token 批次会抛出ValueErrortoken 值必须落在无符号 32 位范围内0 token u32::MAX否则同样报ValueError。truncate_sequenceTrue时超长序列会被截断而非报错。调用方式为runner.send_embedding_request(request)返回list[list[float]]即每个输入对应一条嵌入向量。可运行示例见 embedding_gemma.py其中用Which.Embedding加载google/embeddinggemma-300m并批量计算两个查询的向量。LoraAdapterGeneration锁定精确的适配器代LoraAdapterGeneration是一个frozen数据类只有一个字段字段类型generationstr它用于按64 字符的 generation ID精确选定某一个不可变的 LoRA 适配器代。所谓代是指一次动态 LoRA 加载/替换产生的不可变版本同一个别名alias可以先后对应多个 generation而LoraAdapterGeneration允许你在请求中锁定当时测试过的那个精确版本避免别名被更新后行为漂移。从源码看requests.rs 中该结构内部持有AdapterGenerationId构造时通过generation.parse()做严格校验——不是合法的 64 字符 ID 会抛出ValueError测试用例exact_adapter_generation_is_validated_and_converted验证了这一点。其典型用法是配合动态 LoRA 生命周期 APIloaded runner.load_lora_adapter(production, adapter_dir) # 返回 LoraAdapterInfo exact loaded.exact() # - LoraAdapterGeneration res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[{role: user, content: 你好}], adapterexact, # 锁定该精确 generation ) )完整生命周期加载、别名路由、精确代路由、替换、CAS 校验、卸载见 lora.py。请求构造的底层验证综合 requests.rs 与 request.rs请求数据类的构造遵循以下可验证行为参数位置与关键字限制adapter在两个请求类中都是*之后的关键字参数测试用例adapter_selection_is_keyword_only_after_existing_request_arguments直接断言了构造签名以*, adapterNone结尾推理控制的校验顺序先解析reasoning_effort字符串trim 大小写不敏感off/none→Offmax别名xhigh再由resolve_reasoning_controls检查与enable_thinking的矛盾并计算生效的思考开关权限合并code_execution_permission作为旧接口自动并入agent_permission请求只能收紧而不能放宽 Runner/服务端的权限基线流式与批处理streamTrue使send_chat_completion_request返回 chunk 生成器n_choices 1时每个响应携带多个Choice。最小可运行示例结合以上字段一个最小对话请求只需messages与model示例改写自 plain.pyfrom mistralrs import Runner, Which, ChatCompletionRequest, Architecture runner Runner( whichWhich.Plain( model_idmistralai/Mistral-7B-Instruct-v0.1, archArchitecture.Mistral, ), ) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ {role: user, content: Tell me a story about the Rust type system.} ], max_tokens256, presence_penalty1.0, top_p0.1, temperature0.1, ) ) print(res.choices[0].message.content) print(res.usage)流式输出只需把streamTrue加入请求并迭代 chunk见 streaming.py工具调用则在请求中传入tool_schemas与tool_choiceToolChoice.Auto见 tool_call.py。小结ChatCompletionRequest、CompletionRequest、EmbeddingRequest是 mistral.rs Python SDK 与引擎交互的三个核心入口对话请求承载了最丰富的配置面——采样、结构化约束、推理控制、工具与 Agent 权限、文件输入输出和动态 LoRA 路由补全请求面向原始文本续写嵌入请求面向向量计算。而LoraAdapterGeneration则提供了在多代适配器并存时锁定精确版本的能力。理解这些数据类的字段语义与底层校验逻辑是高效、安全地使用 mistral.rs 构建应用的基础。如需进一步查阅响应类型、枚举定义与 Runner 的其他方法可继续阅读 responses.md、enums.md 与 runner.md。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考