mistral.rs OpenAI 兼容 Skills 上传与使用实战：基于 `--agent` 与 Shell 执行器装载技能包

mistral.rs OpenAI 兼容 Skills 上传与使用实战基于--agent与 Shell 执行器装载技能包【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本文以 mistral.rs 官方示例examples/server/skills.py为主线讲解如何通过 OpenAI 兼容接口把「技能包Skill」以 ZIP 形式上传到推理服务并在 Responses API 中通过skill_reference引用它让模型在沙箱 Shell 环境中按SKILL.md指令执行捆绑脚本。读完本文你将掌握 Skill 包的目录规范、上传接口的校验规则、引用参数写法以及服务端从「上传 → 持久化 → 解析引用 → 装载进会话」的完整调用链。一、功能定位与前置条件Skills 是 mistral.rs 服务端提供的一种可上传工具包能力把一个包含SKILL.md说明文件、辅助脚本和数据文件的目录打包上传到服务器随后在 Responses 请求中以skill_reference引用它服务端会把该目录装载进 Shell 工具的工作目录skills/skill-name模型先阅读SKILL.md再按指引运行捆绑脚本。Skills 依赖 Shell 执行器因此--enable-shell是最低要求的启动参数需要完整的 Agent 运行时工具循环、系统提示注入等时使用--agent。官方文档 skills.md 给出的启动命令为mistralrs serve --agent -p 1234 -m Qwen/Qwen3-4B启动后运行示例脚本python examples/server/skills.py完整的可运行示例位于 examples/server/skills.py服务端核心实现位于 mistralrs-server-core/src/skills.rs。二、客户端初始化OpenAI 兼容端点示例通过openaiPython SDK 连接 mistral.rs 的/v1兼容端点。模型名固定为defaultAPI Key 任意填写如foobarfrom openai import OpenAI BASE_URL http://localhost:1234/v1 API_KEY foobar MODEL default client OpenAI(api_keyAPI_KEY, base_urlf{BASE_URL}/)注意base_url以/v1结尾而 Skills 上传路径写为/skills二者拼接后实际请求的是POST http://localhost:1234/v1/skills与服务端路由POST /v1/skills对应见 skills.rs 中upload_skill处理器。三、构造 Skill 包SKILL.md 捆绑文件示例构造了一个发票审计技能invoice-auditor目录内包含三个文件SKILL.md技能说明必须包含 YAML frontmattername与description正文是给模型的操作指引invoice.csv待校验的发票数据check_invoice.py执行校验的 Python 脚本。from pathlib import Path def write_sample_skill(root: Path) - Path: skill_dir root / invoice-auditor skill_dir.mkdir() (skill_dir / SKILL.md).write_text( --- name: invoice-auditor description: Checks invoice line items and totals with a local Python helper. --- # Invoice Auditor Use python3 skills/invoice-auditor/check_invoice.py skills/invoice-auditor/invoice.csv to validate the bundled invoice. Report whether the declared total matches the sum of the line items. , encodingutf-8, ) (skill_dir / invoice.csv).write_text( item,amount hosting,25.00 storage,12.50 support,17.50 declared_total,55.00 , encodingutf-8, ) (skill_dir / check_invoice.py).write_text( import csv import sys with open(sys.argv[1], newline) as handle: rows list(csv.DictReader(handle)) declared float(rows[-1][amount]) line_total sum(float(row[amount]) for row in rows[:-1]) print(fline_total{line_total:.2f}) print(fdeclared_total{declared:.2f}) print(statusmatch if line_total declared else statusmismatch) , encodingutf-8, ) return skill_dir注意SKILL.md正文中给出的命令路径是skills/invoice-auditor/...——这正是技能被装载进 Shell 会话后的挂载路径前缀详见第六节。四、打包与上传multipart ZIP 上传技能目录先压缩为 ZIP再以 multipart 文件形式 POST 到/skillsimport tempfile import zipfile def zip_skill(skill_dir: Path, zip_path: Path) - None: with zipfile.ZipFile(zip_path, w, zipfile.ZIP_DEFLATED) as archive: for path in skill_dir.rglob(*): archive.write(path, path.relative_to(skill_dir.parent)) def upload_skill(zip_path: Path) - dict: with zip_path.open(rb) as handle: return client.post( /skills, cast_todict, files{file: (zip_path.name, handle, application/zip)}, )整个流程放在临时目录中完成with tempfile.TemporaryDirectory() as temp_dir: temp_path Path(temp_dir) skill_dir write_sample_skill(temp_path) zip_path temp_path / invoice-auditor.zip zip_skill(skill_dir, zip_path) skill upload_skill(zip_path) print(fUploaded skill: {skill[id]} ({skill[name]}))上传成功后返回的skill对象至少包含id形如skill_uuid与name后续引用时使用skill[id]。服务端上传校验源码级从 skills.rs 的实现可以确认服务端对上传的约束体积与数量限制单次上传总大小不得超过MAX_SKILL_UPLOAD_BYTES 50 * 1024 * 102450 MiB文件数不得超过MAX_SKILL_FILES 500ZIP 安全校验extract_zip会拒绝包含符号链接symlink的条目并通过enclosed_name()拒绝任何存在路径穿越风险的条目目录结构find_skill_root要求上传内容要么在根目录直接包含SKILL.md要么恰好只有一个顶层文件夹且其中包含SKILL.md否则报invalid_skill_uploadfrontmatter 解析read_skill_metadata要求SKILL.md以---开头的 YAML frontmatter且其中必须含非空的name与description文件本身必须是合法 UTF-8持久化create_skill为每个技能生成skill_uuid形式的 ID内容存放到SkillStore.root/skill_id/versions/version/content目录元数据以skill.json写入磁盘SkillStore默认根目录为系统临时目录下的mistralrs-skillsSkillStore::default_root版本管理首次上传即版本 1POST /v1/skills/{skill_id}/versions可追加新版本版本号自增。五、在 Responses 请求中引用技能上传完成后通过client.responses.create发起推理请求在tools中声明 Shell 工具并在environment.skills里以skill_reference引用刚上传的技能from pprint import pprint response client.responses.create( modelMODEL, input( Use the uploaded invoice-auditor skill. Read its instructions, run its bundled invoice check, and report the result. ), tools[ { type: shell, environment: { type: container_auto, skills: [ { type: skill_reference, skill_id: skill[id], version: latest, } ], }, } ], tool_choicerequired, )关键字段说明字段取值含义tools[].typeshell启用 Shell 工具依赖--enable-shellenvironment.typecontainer_auto自动创建沙箱容器作为执行环境skills[].typeskill_reference引用已上传技能而非本地路径skills[].skill_id上传返回的skill[id]唯一标识skills[].versionlatest取最新版本也可填具体版本号字符串或数字tool_choicerequired强制模型必须调用工具从 openai.rs 的类型定义可见OpenAiShellEnvironment支持container_auto、local、container_reference三种形态OpenAiShellSkill支持skill_reference与local两种其中local技能与local环境在into_skill_references中被显式拒绝tools[].type\shell\ local skills are not supported.因此通过 OpenAI 兼容接口只能引用已上传的技能。version字段在服务端SkillStore::resolve_reference中解析None或字符串latest取最后一个版本数字或数字字符串按精确版本匹配。六、运行结果与底层装载原理请求完成后打印两个层面的结果print(\nSkill response:) print(response.output_text) print(\nRaw response output:) pprint(response.output)response.output_text是最终面向用户的文本回复response.output是结构化工具调用记录可以看到模型先读取SKILL.md、再执行check_invoice.py、最后汇总statusmatch/mismatch的完整轨迹。底层装载链路按源码梳理引用解析服务端SkillStore::resolve_references将skill_reference解析为ShellSkillMount { name, description, source_path }skills.rs目录装载Shell 会话创建时mount_skills把技能内容拷贝到会话工作目录下的skills/skill-name名称经safe_skill_dir_name清洗为字母、数字、-、_见 shell.rs系统提示注入inject_shell_skills_message会在请求消息头部插入一条 system 消息明确告诉模型技能是挂载在工作目录下的文件夹而非 PATH 命令使用前必须先cat skills/skill-name/SKILL.md并附上技能的描述与文件树File tree:列表见 agentic_loop.rs。这解释了为什么SKILL.md正文中的命令路径要以skills/invoice-auditor/...开头执行与产物回传Shell 工具在执行过程中新写入的文件会被识别为可下载的 File 对象回传客户端见 tools.rs。七、扩展点与注意事项Anthropic 兼容形态Skills 路由同时支持 Anthropic 风格的请求。当请求携带anthropic-version/anthropic-beta头或source查询参数时上传、列表、版本接口会返回 Anthropic 形态的 JSON 结构如AnthropicSkillObject错误响应也会切换为 Anthropic 错误包裹格式相关单元测试覆盖了这一分支技能列表与版本查询GET /v1/skills返回全部已上传技能GET /v1/skills/{skill_id}/versions返回某技能的全部版本便于客户端在引用前做检查--enable-shell与--agent的取舍仅做单轮 Shell 调用时--enable-shell已够用需要多轮工具循环、技能提示注入等完整 Agent 能力时使用--agent错误语义上传内容不合法返回 400invalid_skill_upload超过体积限制返回 413技能或版本不存在返回 404skill_not_found与 OpenAI/Anthropic 错误结构对齐。八、相关资源示例源码examples/server/skills.py服务端 Skills 存储与路由实现mistralrs-server-core/src/skills.rsShell 工具与技能引用类型定义mistralrs-server-core/src/openai.rs技能系统提示注入与文件树生成mistralrs-core/src/engine/agentic_loop.rsShell 会话中的技能装载mistralrs-code-exec/src/shell.rsShell 工具提示与产物回传mistralrs-code-exec/src/tools.rs【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考