企业官网建设流程全解析

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）形式暴露，分别对应引擎的三类核心能力：

这些数据类在 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

它支持三种形态：

1. 普通对话消息：list[dict[str, str]]，即{"role": ..., "content": ...}列表，是最常用的形态；
2. 带图片等多模态内容的对话消息：list[dict[str, list[dict[str, str | dict[str, str]]]]]，用于聊天补全携带图像（以及语音、视频输入）的场景；
3. 预模板化 prompt：直接传str，此时 mistral.rs 不会套用对话模板，而是把该字符串当作已经渲染好的提示词直接送入引擎。

从源码看，requests.rs 在构造时通过downcast_exact::<PyList>()与downcast_exact::<PyString>()精确区分列表与字符串两种输入；若不是这两种类型则抛出TypeError("Expected a string or list of dicts.")。

完整字段表

以下是ChatCompletionRequest的全部字段（与原文档一致，并补充了便于实操的说明）：

采样参数说明

• 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_eos=True时不把 EOS 当作结束标记，常用于强制续写或结构化抽取；
• logprobs=True时开启对数概率返回，配合top_logprobs可拿到每个位置的前 N 个候选 token 的概率分布；
• stream=True时send_chat_completion_request返回一个生成器，逐块产出ChatCompletionChunkResponse（见 responses.md）。

结构化输出：grammar 与 grammar_type

grammar与grammar_type配合使用，用于约束解码过程，保证输出符合指定格式。grammar_type取值包括regex、json_schema、llguidance等。仓库中提供了多个可直接运行的示例：

• 正则约束：regex.py 用grammar_type="regex", grammar=r"[0-9A-Z ]+"强制输出只含大写字母、数字与空格；
• JSON Schema 约束：json_schema.py 以 JSON 字符串形式传入 schema（含字段类型、pattern、minimum/maximum、required等约束）；
• llguidance 约束：llguidance.py 使用 LARK 文法与内联 JSON schema 组合，grammar_type="llguidance"。

在引擎侧，约束最终会转换为Constraint::Regex/Constraint::JsonSchema/Constraint::Llguidance等变体（见 request.rs），由采样器在每一步解码时强制执行。

推理控制：enable_thinking 与 reasoning_effort

reasoning_effort用于配置推理模型的思考强度，接受off、low、medium、high、xhigh五个取值，其中none是off的别名。解析时值会被trim并做大小写不敏感处理。enable_thinking是一个独立的布尔开关。

两条规则需要特别注意（原文档明确说明）：

1. 如果两个推理控制字段都省略，则默认开启思考（DEFAULT_ENABLE_THINKING = true），但不指定具体 effort 级别；
2. 如果enable_thinking与reasoning_effort取值相互矛盾，构造函数会抛出ValueError，例如enable_thinking=True搭配reasoning_effort="off"，或enable_thinking=False搭配reasoning_effort="high"。

从源码看，这一逻辑在 request.rs 的resolve_reasoning_controls中实现：(Some(true), Some(Off))报OffWithThinkingEnabled，(Some(false), Some(非 off 值))报EffortWithThinkingDisabled；effort 的解析（FromStr）在 request.rs，trim().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_choice：ToolChoice.NoTools或ToolChoice.Auto，控制是否允许模型发起工具调用（枚举定义见 enums.md）；
• max_tool_rounds：引擎自动执行工具调用的最大轮数。配合Runner(tool_callbacks=...)注册的 Python 回调或tool_dispatch_url指定的外部 HTTP 端点，引擎会在模型-工具之间自动循环执行并回填结果（完整示例见 agentic_tools.py）；
• enable_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.rs）；
• session_id：持久化 Agent 会话的 ID，跨请求保留工具执行上下文。

agent_permission字段作用于所有由服务端执行的 Agent 动作——包括代码执行、Shell、Web 搜索、文件工具、回调以及外部工具分发，取值为AgentPermission.Auto、.Ask或.Deny：

• auto：工具调用合法时立即执行；
• ask：执行前暂停，通过agent_approval_callback请求审批；
• deny：工具对模型保持可见，但直接返回被拒绝的工具结果而不真正执行。

agent_approval_callback在agent_permission=AgentPermission.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.md）；
• web_search_options：WebSearchOptions对象，用于配置内置 Web 搜索工具（search_context_size、user_location、search_description、extract_description）。要使用该功能，Runner需以enable_search=True构建（示例见 web_search.py，类型定义见 search.md）。

adapter 字段

adapter是ChatCompletionRequest中唯一标注为仅限关键字参数（keyword-only）的字段，用于在请求级路由 LoRA 适配器，接受两种取值：

• 字符串别名（alias）：选择当前加载到该别名下的最新适配器代（generation）；
• LoraAdapterGeneration对象：锁定某一个不可变的精确 generation。

在 requests.rs 的parse_adapter_selection中，先尝试把值解析为字符串别名，再尝试解析为LoraAdapterGeneration，都不是则抛出TypeError。请求完成后，响应中的adapter_generation字段会回显实际使用的 generation（示例见 lora.py）。

CompletionRequest：原始文本补全

CompletionRequest表示发送给引擎的一次原始补全请求，直接给定一段文本 prompt 让模型续写，不经过对话模板。其完整字段如下：

与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表示一次嵌入计算请求，字段最少：

input的四种形态在 requests.rs 的normalize_embedding_inputs中被规范化：

• 单个字符串：按单个 prompt 处理；
• list[str]：批量 prompt，列表中元素个数即返回的向量条数；
• list[int]：单条 token 序列（token ID 列表）；
• list[list[int]]：批量 token 序列。

该函数还会做两类校验：空的字符串列表或 token 批次会抛出ValueError；token 值必须落在无符号 32 位范围内（0 <= token <= u32::MAX），否则同样报ValueError。truncate_sequence=True时超长序列会被截断而非报错。

调用方式为runner.send_embedding_request(request)，返回list[list[float]]，即每个输入对应一条嵌入向量。可运行示例见 embedding_gemma.py，其中用Which.Embedding加载google/embeddinggemma-300m并批量计算两个查询的向量。

LoraAdapterGeneration：锁定精确的适配器代

LoraAdapterGeneration是一个frozen数据类，只有一个字段：

它用于按64 字符的 generation ID精确选定某一个不可变的 LoRA 适配器代。所谓"代"，是指一次动态 LoRA 加载/替换产生的不可变版本：同一个别名（alias）可以先后对应多个 generation，而LoraAdapterGeneration允许你在请求中锁定当时测试过的那个精确版本，避免别名被更新后行为漂移。

从源码看，requests.rs 中该结构内部持有AdapterGenerationId，构造时通过generation.parse()做严格校验——不是合法的 64 字符 ID 会抛出ValueError（测试用例exact_adapter_generation_is_validated_and_converted验证了这一点）。其典型用法是配合动态 LoRA 生命周期 API：

loaded = runner.load_lora_adapter("production", adapter_dir) # 返回 LoraAdapterInfo exact = loaded.exact() # -> LoraAdapterGeneration res = runner.send_chat_completion_request( ChatCompletionRequest( model="default", messages=[{"role": "user", "content": "你好"}], adapter=exact, # 锁定该精确 generation ) )

完整生命周期（加载、别名路由、精确代路由、替换、CAS 校验、卸载）见 lora.py。

请求构造的底层验证

综合 requests.rs 与 request.rs，请求数据类的构造遵循以下可验证行为：

1. 参数位置与关键字限制：adapter在两个请求类中都是*之后的关键字参数，测试用例adapter_selection_is_keyword_only_after_existing_request_arguments直接断言了构造签名以*, adapter=None结尾；
2. 推理控制的校验顺序：先解析reasoning_effort字符串（trim+ 大小写不敏感，off/none→Off，max别名xhigh），再由resolve_reasoning_controls检查与enable_thinking的矛盾并计算生效的思考开关；
3. 权限合并：code_execution_permission作为旧接口自动并入agent_permission，请求只能收紧而不能放宽 Runner/服务端的权限基线；
4. 流式与批处理：stream=True使send_chat_completion_request返回 chunk 生成器；n_choices > 1时每个响应携带多个Choice。

最小可运行示例

结合以上字段，一个最小对话请求只需messages与model（示例改写自 plain.py）：

from mistralrs import Runner, Which, ChatCompletionRequest, Architecture runner = Runner( which=Which.Plain( model_id="mistralai/Mistral-7B-Instruct-v0.1", arch=Architecture.Mistral, ), ) res = runner.send_chat_completion_request( ChatCompletionRequest( model="default", messages=[ {"role": "user", "content": "Tell me a story about the Rust type system."} ], max_tokens=256, presence_penalty=1.0, top_p=0.1, temperature=0.1, ) ) print(res.choices[0].message.content) print(res.usage)

流式输出只需把stream=True加入请求并迭代 chunk（见 streaming.py）；工具调用则在请求中传入tool_schemas与tool_choice=ToolChoice.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