mistral.rs HTTP 服务器文本补全/v1/completions实战指南【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本文以 mistral.rs 仓库中可运行的 HTTP 服务器示例completion为主线讲解如何基于 OpenAI 兼容的/v1/completions端点对纯文本模型发起补全请求。你将掌握从启动serve服务器、使用openaiPython 客户端交互式调用到理解请求参数在服务端如何被解析为采样配置的完整链路并学会排查与调试 HTTP 请求/响应。示例概览一个可运行的文本补全客户端docs/src/content/docs/examples/server/completion.md文档由 render_examples.py 从源码示例自动生成对应仓库中的 examples/server/completion.py 文件。它是一个最小但完整的 HTTP 服务器客户端示例演示了使用官方openaiPython SDK 连接 mistral.rs 的 OpenAI 兼容 API通过client.completions.create()调用文本补全端点在 REPL 循环中不断读取用户输入并打印模型输出提供可选的 httpx 请求/响应日志钩子用于调试网络层细节。该示例假设模型已通过mistralrs serve命令加载并监听在localhost:1234上——这正是mistralrsHTTP 服务器的默认端口。第一步启动文本补全服务器示例客户端连接http://localhost:1234/v1/对应服务器端的默认配置。mistralrs-cli的serve子命令负责加载模型并启动 HTTP 服务其默认端口定义为 1234、绑定地址为0.0.0.0见 ServerOptions 定义。# 以交互式模型源启动-i并指定端口默认已是 1234 mistralrs serve --port 1234 -i --model-id 模型ID对于本地 GGUF 文件可以改为显式指定量化文件mistralrs serve --port 1234 -i -f 模型.gguf --model-id 模型ID服务启动后run_server会打印 API 面信息见 serve.rs 的 log_api_surfaces其中包含OpenAI-compatible API: http://localhost:1234/v1与Swagger UI docs: http://localhost:1234/docs。此时/v1/completions端点即已就绪。注意/v1/completions是 OpenAI 的旧版文本补全Text Completion端点只接收纯文本prompt而不走 Chat 模板。mistralrs同时提供/v1/chat/completions对话补全与/v1/completions文本补全本示例聚焦后者。完整示例代码解读以下是 examples/server/completion.py 的完整内容它也是本文档的核心from openai import OpenAI import httpx import textwrap import json def log_response(response: httpx.Response): request response.request print(fRequest: {request.method} {request.url}) print( Headers:) for key, value in request.headers.items(): if key.lower() authorization: value [...] if key.lower() cookie: value value.split()[0] ... print(f {key}: {value}) print( Body:) try: request_body json.loads(request.content) print(textwrap.indent(json.dumps(request_body, indent2), )) except json.JSONDecodeError: print(textwrap.indent(request.content.decode(), )) print(fResponse: status_code{response.status_code}) print( Headers:) for key, value in response.headers.items(): if key.lower() set-cookie: value value.split()[0] ... print(f {key}: {value}) client OpenAI(api_keyfoobar, base_urlhttp://localhost:1234/v1/) # Enable this to log requests and responses # client._client httpx.Client( # event_hooks{request: [print], response: [log_response]} # ) while True: prompt input( ) completion client.completions.create( modeldefault, promptprompt, max_tokens256, frequency_penalty1.0, top_p0.1, temperature0, ) resp completion.choices[0].text print(resp)客户端初始化与modeldefaultclient OpenAI(api_keyfoobar, base_urlhttp://localhost:1234/v1/)api_key可以是任意占位符如foobar因为 mistral.rs 本地服务器不校验密钥只要求请求带上 Authorization 头以保持 OpenAI 协议兼容base_url必须指向服务器的/v1/前缀客户端后续所有路径如/v1/completions都基于它拼接。请求中的modeldefault是一个约定值在 CompletionRequest 结构体 中model字段的 serde 默认值就是default它表示使用当前唯一加载的模型。服务端在 parse_request 中当model default时将model_id置为None即不按模型名路由、直接命中已加载的默认模型。循环调用与采样参数主循环每次读取一行用户输入调用client.completions.create(...)并从completion.choices[0].text取出生成的文本打印。这里传入的四个采样参数在服务端各有对应实现见下文请求参数与采样语义一节max_tokens256限制生成的最大 token 数frequency_penalty1.0按 token 出现频率施加惩罚抑制重复top_p0.1核采样只从累计概率质量前 10% 的 token 中采样temperature0贪心解码输出确定性最强。可选的 HTTP 调试钩子示例中注释掉的client._client httpx.Client(...)通过 httpx 的event_hooks在请求发出前打印请求行在响应返回后调用log_response打印完整的请求/响应头与请求体。log_response中做了两类隐私处理authorization头一律替换为[...]避免泄露 api_keycookie与set-cookie只保留key...前缀避免打印完整 Cookie 值。打开这组钩子后你可以直观看到 SDK 实际发送的 JSON 请求体以及服务器返回的状态码、content-type等头信息非常适合排查参数未生效或网络异常的问题。请求参数与采样语义从 HTTP 到引擎/v1/completions的请求体由 CompletionRequest 结构体 定义。除了示例中使用的四个参数它还支持 OpenAI 标准的完整参数集以及 mistral.rs 的扩展字段OpenAI 标准字段字段类型说明modelString模型 ID默认default命中唯一加载的模型promptString输入提示文本必填max_tokensusize最大生成 token 数别名max_completion_tokens服务端校验max_tokens 0会直接报错见 completions.rs 校验逻辑temperaturef64采样温度越高越随机top_pf64核采样概率阈值frequency_penaltyf32按频率惩罚已出现 token正值抑制重复presence_penaltyf32惩罚已出现过的 token无论频率正值鼓励转向新话题logit_biasHashMapu32, f32采样前对指定 token ID 的 logits 添加偏置logprobsusize返回该数量个最可能 token 的 log 概率nn_choicesusize生成多少个候选补全默认 1stopstop_seqsString | [String]停止序列命中即终止生成echoecho_promptbool是否在补全文本前回显 prompt默认 falsesuffixString追加在补全之后的文本best_ofusize服务端生成多个候选并取最优服务端将其透传进RequestMessage::Completionseedu64固定随机种子使请求级采样可复现ignore_eosbool忽略模型 EOS token仅受显式 stop 与 token 上限约束streambool是否以 SSE 流式返回默认 falseuserString透传的用户标识服务端忽略mistral.rs 扩展字段字段类型说明top_kusize仅从概率最高的 k 个 token 中采样min_pf64丢弃概率低于最高 token 概率 × min_p的 tokenrepetition_penaltyf32乘法式重复惩罚1.0 表示关闭grammarobject约束输出regex、json_schema、lark或llguidance四种语法对应 Constraint 枚举映射dry_multiplier/dry_base/dry_allowed_length/dry_sequence_breakers—DRY 重复惩罚采样器参数由 get_dry_sampling_params 组装为DrySamplingParamstruncate_sequencebool输入超过模型上下文长度时截断而非报错tools/tool_choice—供工具调用使用文本补全端点同样透传服务端 parse_request 将上述字段逐一映射到内部的NormalRequest与SamplingParamstemperature、top_k、top_p、min_p、top_n_logprobs、frequency_penalty、presence_penalty、repetition_penalty、max_len、stop_toks、logits_bias、n_choices等被原样传入采样器prompt、echo_prompt、best_of则装入RequestMessage::Completion。这意味着你在 HTTP 层看到的每个采样参数最终都会精确作用于引擎的采样过程。服务端处理流程与流式响应路由与响应类型/v1/completions的处理器是 completions 函数流程为反序列化请求体JSON 解析失败返回ValidationError调用resolve_lora_adapter_model解析 LoRA adapter 覆盖若有调用parse_request转换为内部请求并发送给引擎send_request_with_model根据stream字段分流非流式走process_non_streaming_response等引擎产出Response::CompletionDone后包装为CompletionResponder::Json返回流式构建CompletionStreamer以 SSEServer-Sent Events逐 chunk 推送结束时发送data: [DONE]事件。响应统一由CompletionResponder枚举承载见 completion_core.rs包括Json完整响应、Sse流式、ModelError、InternalError、ValidationError五种形态其IntoResponse实现completions.rs负责把内部错误翻译为 OpenAI 风格的 JSON 错误响应。流式 chunk 与错误事件流式模式下CompletionStreamer 的 poll_next 每次从通道收到Response::CompletionChunk就将其序列化为一条 SSE 事件当所有choices的finish_reason都已就绪时进入DoneState::SendingDone推送[DONE]结束标记。期间若发生模型错误、校验错误或内部错误也会以 OpenAI 兼容的错误事件形式注入流中而非直接断开连接。流式响应支持两个扩展钩子CompletionOnChunkCallback在 chunk 发送前回调可用于内容过滤、改写或日志例如 completions.rs 中展示的用法CompletionOnDoneCallback流结束后收到全部 chunks适合做统计与分析。非流式响应体中usage字段由 CompletionUsageResponse 定义除 OpenAI 标准的prompt_tokens、completion_tokens、total_tokens外还额外包含cached_tokens前缀缓存命中的 token 数以及avg_tok_per_sec、total_time_sec等吞吐统计字段——这些是 mistral.rs 在兼容层之上提供的性能观测能力。其他调用方式使用 curl 一次性调用不依赖任何 Python 依赖即可验证端点curl http://localhost:1234/v1/completions \ -H Content-Type: application/json \ -d { model: default, prompt: The capital of France is, max_tokens: 32, temperature: 0 }流式调用curl -N http://localhost:1234/v1/completions \ -H Content-Type: application/json \ -d { model: default, prompt: Once upon a time, max_tokens: 64, stream: true }-N禁用 curl 缓冲可以实时看到 SSE 事件流最后一行是data: [DONE]。小结completion示例演示了 mistral.rs HTTP 服务器最基础的文本补全路径serve启动 OpenAI 兼容服务 → SDK 以modeldefault命中已加载模型 → 采样参数经parse_request映射进引擎。在它之上你还可以进一步组合stop停止序列、seed复现、grammar结构化约束与stream流式输出把/v1/completions改造成满足具体业务需求的补全服务。相关源码均可在此仓库中继续深挖Python 示例、路由与解析实现、请求结构体定义、serve 命令入口。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考