FineTune Studio：用 MCP 在 Claude 中零代码微调 Hugging Face 模型的全流程实战

FineTune Studio：用 MCP 在 Claude 中零代码微调 Hugging Face 模型的全流程实战

【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub

导读

FineTune Studio 是一个基于 Model Context Protocol（MCP）的微调应用：它以 MCP Server + 前端 Widget 的形式运行在 Claude 内部，让开发者"不写一行代码"即可完成"选基座模型 → 选数据集 → 配超参 → 发起训练 → 与微调后模型对话"的完整闭环。本指南将带你从克隆仓库、准备 Hugging Face（下称 HF）账号与 AutoTrain Advanced Space、部署到 Manufact MCP Cloud、接入 Claude，到逐项解析四步训练向导与 MCP 工具背后的源码实现，帮助你在 20 分钟级成本内跑通第一个 LoRA 微调模型。

一、方案概览：它到底做了什么

从整体架构看，FineTune Studio 把所有"重活"外包给了 HF 生态，自身只做编排与交互：

• 训练执行层：调用Hugging Face AutoTrain Advanced完成 GPU 训练（通过你账号内自主托管的 Space，费用直接计入你的 HF 账号）；
• 推理发布层：训练完成后自动在你名下创建一个私有可控的Gradio Inference Space，加载 LoRA 合并后的模型权重并提供对话接口；
• 运行承载层：以 MCP Server 部署在 Manufact MCP Cloud，借助其环境变量、日志、指标与 GitHub 自动部署能力接入 Claude Desktop；
• 交互表现层：launch_studio等工具通过@modelcontextprotocol/ext-apps把编译为单 HTML 的 Widget 渲染进 Claude 侧边栏。

README 给出的完整流程可以概括为：

Clone 仓库 → 创建 HF 账号并获取 Write Token → 为 GPU 时间充值 HF Credits → 将 AutoTrain Space 复制到你的 HF 账号 → 部署到 Manufact（CLI 或 GitHub 自动部署） → 在 Manufact 面板配置 HF_TOKEN → 打开 Claude，通过 FineTune Studio 发起训练 → 与微调后的模型对话

下文将按这个链路逐步展开，并在关键节点对照本仓库源码（server.ts 与 src/mcp-app.ts）说明底层实现，方便你既会"用"，也懂"为什么"。

二、获取代码与工程结构

git clone <仓库地址> finetune-studio-mcp-app cd finetune-studio-mcp-app npm install

关键源码文件如下（对应 README 的 Project Structure，并结合实际仓库核对）：

package.json中的脚本决定了整个构建-运行链路：

{ "scripts": { "build": "INPUT=widget.html vite build", "start": "npx tsx server.ts", "serve": "npx tsx server.ts", "dev": "npm run build && npx tsx server.ts" } }

• npm run build用widget.html作为 Vite 入口，配合 vite.config.ts 中的viteSingleFile()插件把所有前端资源内联为单个dist/widget.html；
• npm start/npm run serve直接用tsx运行 server.ts；
• npm run dev在启动前自动先构建一次前端。

依赖上，运行时核心是@modelcontextprotocol/sdk、@modelcontextprotocol/ext-apps、@gradio/client、express、cors与zod；构建侧使用vite、vite-plugin-singlefile与 TypeScript。需要说明：@gradio/client虽在依赖中，但源码实际对 Gradio 4.x 的调用是走原生 HTTP + SSE 实现的（见下文"推理链路"），以获取更完整的错误控制。

三、Part 2：Hugging Face 侧的四个准备步骤

FineTune Studio 自身不持有任何 GPU，训练全部发生在 HF 付费硬件上，因此 HF 账号是必需前置条件。

3.1 创建账号并充值 Credits

在 HF 官网注册后，进入 Billing（账单）页的Credits区块购买积分，建议至少充值 5 美元起步。注意：Credits 只在训练任务实际运行时才被消耗，Space 空闲不扣费。

README 给出了按硬件区分的参考成本（因 GPU 定价会随供应商调整，此处仅作数量级参考）：

3.2 创建 Write 权限 Token

进入 Tokens 设置页新建 token，命名随意（如finetune-studio），角色务必选择Write——因为应用需要替你在 HF 上创建 Space、推送模型。生成的 token 以hf_开头，请妥善保管：任何拿到它的人都能读写你的整个 HF 账号。该 token 后续会被写入两处：AutoTrain Space 的 secret 与服务端环境变量。

3.3 复制 AutoTrain Advanced Space（关键一次性步骤）

AutoTrain Advanced 需要在你的账号内运行，训练账单才会归属到你名下。操作路径是打开官方 Spaceautotrain-projects/autotrain-advanced，点击Duplicate this Space：

复制时注意：

• Owner选择你的用户名；
• 名称保持为autotrain-advanced（服务端按这个固定名查找，见下文源码解析）；
• 可见性设为 Private——该 Space 内会存放你的 token；
• 硬件选择 CPU Basic即可，训练任务由 AutoTrain 按需另起 GPU 容器；
• 点击Duplicate Space。

随后进入你自己的 Space（路径形如你的用户名/autotrain-advanced），在Settings → Repository secrets中新建 secret，键名为HF_TOKEN，值粘贴第 3.2 步的 token，保存后 Space 会自动重启并应用该 secret。此步骤只需执行一次。

为什么必须叫这个名字？从源码可见，server.ts 中定义了const AUTOTRAIN_SPACE_NAME = "autotrain-advanced"，训练启动前会调用hfGet请求/api/spaces/{username}/autotrain-advanced并读取其subdomain字段：

const AUTOTRAIN_SPACE_NAME = "autotrain-advanced"; // 查 Space 信息，subdomain 即 .hf.space URL 的 slug const spaceInfo = await hfGet(`${HF_API}/spaces/${username}/${AUTOTRAIN_SPACE_NAME}`); spaceSubdomain = spaceInfo.subdomain || "";

如果找不到该 Space，start_training工具不会直接报错，而是返回一段带setup_required: true的可操作引导信息，指导你完成复制与命名，再重试。

四、Part 3：部署到 Manufact MCP Cloud

Manufact 为该应用的线上宿主：提供生产级部署、按分支的预览 URL、实时日志、工具调用指标与 JSON-RPC 追踪，且无需手写 Docker 或 YAML。部署方式有两种。

4.1 Option A：CLI 快速部署

# 安装 CLI npm install -g @mcp-use/cli # 登录 Manufact（会自动打开浏览器走授权流程，成功后本地保存会话 token） npx @mcp-use/cli login # 构建并部署 npm run build npx @mcp-use/cli deploy

部署成功后 CLI 会打印线上 URL，形如https://你的服务名.manufact.app/mcp。随后到 Manufact 控制台打开该服务，进入Settings → Environment Variables，新增：

HF_TOKEN = hf_xxxxxxxxxxxxxxxxxxxx

保存后服务端自动重启并加载该环境变量。值得注意的一个实现细节是：源码中 token 并非在进程启动时读取一次，而是通过getHFToken()每次调用时动态读取process.env.HF_TOKEN——这正是为了兼容"Manufact 面板在进程启动后才注入环境变量"的场景：

// 动态读取 token，保证无论环境变量何时注入都是最新值 function getHFToken(): string { return process.env.HF_TOKEN || ""; }

4.2 Option B：GitHub 自动部署（长期迭代推荐）

git remote add origin https://github.com/你的用户名/finetune-studio-mcp.git git push -u origin main

然后在 Manufact 控制台依次操作：

1. 登录后点击New Server；
2. 选择Import from GitHub并授权 Manufact GitHub App；
3. 选择finetune-studio-mcp仓库。Manufact 会自动 clone、build、deploy，此后每次 push 到main都会触发一次自动部署，Pull Request 则获得独立的预览 URL；
4. 在服务Settings → Environment Variables中新增HF_TOKEN，值填hf_...token，保存触发重部署。

仓库内 .github/workflows/ 即为自动化部署的 GitHub Actions 工作流配置所在（若你 fork 后需要深度定制，可在此查看）。

五、Part 4：接入 Claude

服务在 Manufact 上线后，把它注册进 Claude：

1. 打开 Claude，进入Settings → Connectors（或工作区的 MCP 区块）；
2. 添加新的 MCP Server；
3. 粘贴 Manufact 服务 URL，例如https://你的服务名.manufact.app/mcp；
4. 保存。

连接成功后，新建会话输入start fine-tuning studio之类的自然语言提示，FineTune Studio 就会作为工具被唤起，Widget 加载进 Claude 侧边栏。

六、Part 5：四步训练向导实战

Widget 打开后呈现一个四步向导，每一步完成后打勾：

[1] Select Model → [2] Dataset → [3] Configure → [4] Training

6.1 Step 1：选择基座模型

README 建议从适合 LoRA 的小模型入手，并推荐用SmolLM2-135M-Instruct做实验（A10G 上 15 分钟内即可完成）。实际前端默认卡片来自 src/mcp-app.ts 中的POPULAR_MODELS常量，共四款热门的 text-generation 模型：

卡片网格之外还可以通过搜索框检索 HF Hub 上任意模型。点击卡片选中模型后进入下一步。

6.2 Step 2：选择数据集

数据集有两种来源：

来自 Hub：按关键词搜索公共数据集。README 给出的常见选择：

• tatsu-lab/alpaca：指令跟随类（instruction following）；
• HuggingFaceH4/ultrachat_200k：对话类；
• timdettmers/openassistant-guanaco：对话对齐类。

自定义 JSONL（Custom data 标签页）：直接粘贴自己的数据，每行一个合法 JSON 对象。SFT 最常见格式是单行包含text字段：

{"text": "### Instruction:\nSummarize this.\n\n### Response:\nHere is the summary."}

前端会对粘贴内容做实时校验，逐个解析每行并提示格式错误，格式不合法时不允许继续。校验逻辑位于 src/mcp-app.ts 的validateCustomData()，规则是：

• SFT：每行必须有messages或text字段；若用messages，必须是数组且同时包含user与assistant两种角色；
• DPO / ORPO：每行必须同时具备prompt、chosen、rejected三个字段。

对应列映射（column_mapping）默认取text列，这与服务端提交训练时的{ text_column: "text" }一致。

6.3 Step 3：训练配置

向导提供三组可选设置，全部带默认值，可直接点Start Training开跑，也可逐项微调。前端选项（src/mcp-app.ts）与 README 给出的语义对照如下。

训练类型（Training Type）

Chat Template

源码层面的一个关键细节：当用户选择none时，服务端构造请求时会直接省略chat_template字段（见 server.ts 的请求体拼装），注释说明这是因为 AutoTrain 对纯文本数据集套用模板会触发ast.literal_eval语法错误；而前端下拉框依然保留chat_template: "none"的中间态，由服务端负责清洗。

超参数

实现提示：README 表格给出的是推荐档位；打开 Widget 时界面上实际加载的初始值来自 src/mcp-app.ts 的defaultConfig()——其中epochs: 2、batchSize: 1，其余与上表一致；defaultConfig()还会自动生成项目名ft-{模型短名}-{时间戳6位}，如ft-smollm2-1-7b-instruct-418203。你可以在向导里自由调整到上表的推荐档。

LoRA 设置（只训练少量新增低秩参数而非全量权重）：

硬件

服务端硬件标识与前端选项一一对应：spaces-a10g-large、spaces-a10g-small、spaces-t4-medium、spaces-a100-large，其中默认值为spaces-a10g-large。

Project name：训练任务与发布模型共用的名字，最终模型落在huggingface.co/你的用户名/项目名（即 HF 模型 ID你的用户名/项目名）。不填时应用自动生成唯一名。

点击Start Training后，前端调用start_training工具（第 1424 行附近的app.callServerTool({ name: "start_training", ... })）。

6.4 Step 4：监控训练

训练视图每10 秒轮询一次状态（src/mcp-app.ts 中trainingPollTimer = setInterval(..., 10000)），展示：

• 按 epoch 推进的进度条；
• 实时指标：loss、learning rate、当前 epoch；
• 来自训练容器的滚动日志流；
• 右上角的已用时长。

训练结束（日志中出现Training complete、model.*pushed、Pausing space等特征）后，Step 4 变为绿色打勾，出现成功面板：

Training complete! Model ID: yourname/your-project-name Inference Space deployed, building now (~2-3 min). View Space -> [View on Hub] [Chat with model] [Redeploy Space]

三个按钮语义：

• View on Hub：打开微调后模型在 HF 的页面；
• Chat with model：切换到 Inference 标签页并预选好你的模型。Inference Space 需要 2～3 分钟构建容器并加载权重；
• Redeploy Space：把推理应用代码重新推送到 Space，适用于 Space 为空或无法响应时手动修复。

6.5 Inference 标签页：与微调模型对话

Inference 标签页是一个完整聊天界面，支持：

• Space 就绪后与微调模型对话；
• 在自定义模型输入框输入任意公开 HF 模型 ID（默认候选包括meta-llama/Llama-3.2-3B-Instruct、Qwen/Qwen2.5-7B-Instruct、google/gemma-2-2b-it等）切换推理对象；
• 在右上角齿轮设置面板调整 system prompt、temperature、max tokens；
• 用垃圾桶图标清空会话。

七、源码级解析：八工具背后的实现细节

README 中列出的工具表共 7 个；对照 server.ts 实际注册，一共是8 个工具（README 之外还包含为规避 AutoTrain 旧版 bug 而生的patch_autotrain_space）。registerAppTool均来自@modelcontextprotocol/ext-apps/server，其中launch_studio通过_meta.ui.resourceUri关联到ui://finetune-studio/widget.html资源，由registerAppResource将编译后的 dist/widget.html 以单文件 HTML 提供给客户端侧栏渲染。

7.1 start_training：请求如何拼装、训练如何落到你的账号

start_training的完整请求体拼接极具参考价值，它揭示了 AutoTrain Space 接口的几个"坑"（server.ts 内均有注释说明）：

1. 身份字段在顶层：username、token、hub_model必须放在请求体顶层；
2. push_to_hub必须嵌套在顶层hub对象中——放在params里或裸置于顶层都会被 Pydantic 静默丢弃；
3. 训练子 Space 的命名规律是autotrain-{project_name}；
4. 目标 URL 通过账号下autotrain-advancedSpace 的 subdomain 拼出：https://{spaceSubdomain}.hf.space/api/create_project；
5. max_steps在 AutoTrain 的配置字段中并不存在，服务端通过 datasets-server 获取数据行数，估算每 epoch 步数，再把max_steps换算成"最小整数 epoch 数"，并额外把原始max_steps传下去交给 HF Trainer 提前截断，从而兼容"只跑 N 步做快速测试"的需求。

真正有意思的是结果落库的兜底机制：create_project返回后，服务端会向训练子 Space 的 secrets 接口 POST 一个名为PARAMS的 secret，内容是兼容LLMTrainingParams的完整 JSON——其中显式写入push_to_hub: true（源码注释称之为 "THE FIX"）。原因是 AutoTrain 在创建训练子 Space 时会把参数序列化进PARAMS环境变量，而LLMTrainingParams.push_to_hub默认是False且在FIELDS_TO_EXCLUDE中、无法通过 API 覆盖。趁子 Space 尚处 2–5 分钟的构建期更新 secret 触发重启是"免费"的，重启后训练脚本读取新PARAMS即可自动把模型推回 Hub。若该 secret 更新失败则记录 warning 但不阻断训练。

7.2 check_training_status：从容器日志里"考古"出状态

训练监控是源码中最复杂的部分之一，其难点在于 AutoTrain 训练结束后会 pause 自己的 Space，导致 Space 的runtime.stage返回PAUSED/STOPPED时无法区分"还没开始"与"刚结束"。

server.ts 的解法分三层：

1. Stage 归一化：把BUILDING / RUNNING / STOPPED / ERROR / SLEEPING / PAUSED / CONFIG_ERROR / APP_STARTING等原始 stage 映射到starting / training / completed / error四种语义状态；
2. 日志取证：通过/api/spaces/{user}/autotrain-{project}/logs/run的 SSE 端点拉取训练容器日志（4 秒超时后主动reader.cancel()），按data:前缀逐条解析、剥离 ANSI 颜色码；随后用正则匹配SIGTERM、Training complete、model.*pushed、Pausing space等完成签名，把模糊的PAUSED状态修正为completed；
3. 指标提取：从形如{'loss': 9.73, 'learning_rate': 0.0002, 'epoch': 0.02}的日志中提取 loss、epoch、learning_rate，且"永远取最后一次匹配"，避免早期 epoch 的旧值残留在界面上；由于 tqdm 进度条使用\r覆盖行，前端还需结合 totalSteps 用round((epoch / config.epochs) * totalSteps)推算当前步数。

状态变为completed后还会自动执行两件发布动作：

• 调用/api/models/{user}/{project}/settings把模型从 private 翻转为 public（AutoTrain 建仓时硬编码 private）；
• 调用deployInferenceSpace()部署推理 Space（详见下节）。

7.3 自动推理 Space：训练完成后"免费"送你的 Gradio 应用

HF 的 serverless 推理（inferenceProviderMapping）并不服务任意自定义微调模型，因此服务端选择在训练完成时自动部署一个名为inference-{project_name}的 Gradio Space。deployInferenceSpace()（server.ts）的流程是：

1. 幂等建仓：POST/api/repos/create（type=space、sdk=gradio），HTTP 409 表示已存在，跳过；
2. 等待 Git 初始化：新建 Space 的 Git 仓库需要 1–3 秒就绪，过早 commit 会 404，故setTimeout 4000ms；
3. 取 HEAD commit：通过/commits/main拿到当前 commit SHA 作为parentCommit——对非空仓库省略该字段会触发 HTTP 412；
4. 提交代码：以application/x-ndjson批量提交app.py与requirements.txt两个文件（源码中内嵌了模板字符串INFERENCE_APP_PY与INFERENCE_REQUIREMENTS_TXT）；
5. 注入 secret：写入MODEL_ID（模型 ID）与HF_TOKEN。

内嵌的app.py模板非常朴素且有效：用 transformers 的pipeline("text-generation", model=MODEL_ID, ...)加载模型，暴露一个predict(messages_json, max_tokens=512, temperature=0.7)函数供 Gradiogr.Interface包装，api_name="predict"，关闭 flagging。

7.4 chat_with_model：四级降级推理链路

server.ts 的chat_with_model对任意model_id会依次尝试四种推理通道，直到拿到回复：

1. 专属推理 Space（最高优先）：若存在{owner}/inference-{model}Space 且 runtime 为RUNNING，走 Gradio 4.x 的异步队列 API——先POST /gradio_api/call/predict拿到event_id，再GET .../{event_id}以 SSE 形式读取event: complete结果。之所以绕开@gradio/client改用原生 HTTP，是因为官方客户端会静默吞掉连接错误；若 Space 处于 BUILDING/APP_STARTING 或 SLEEPING 状态则给出明确的状态提示；
2. HF Inference Router：把 model_id 拼成${model_id}:fastest打到router.huggingface.co/v1/chat/completions，401/403 时直接提示检查 token 与模型授权；
3. HF Messages API：打到api-inference.huggingface.co/models/{id}/v1/chat/completions；
4. Legacy Text-Generation API：把 messages 拼成 ChatML 提示词后请求api-inference.huggingface.co/models/{id}，并对 503/loading 状态给出含预估等待秒数的提示。

四路全部失败时，最终错误信息会区分"该模型已有推理 Space 在构建中（等待 2–3 分钟）"与"模型在 Hub 上不存在"两种情况，引导用户去对应 Space 排查。

7.5 patch_autotrain_space：对抗上游 bug 的工程实践

README 未提及、但源码实际暴露的第 8 个工具patch_autotrain_space展示了真实项目维护的形态：针对autotrain-advanced ≤ 0.8.36的push_to_hub=Falsebug，它会向你的 AutoTrain Space 仓库提交一个fix_push_to_hub.py脚本与定制Dockerfile。脚本在每次pip install后直接重写磁盘上安装的params.py源码，把"仅当 key 不存在才置 True"的守卫逻辑替换为无条件_params["push_to_hub"] = True，并清空__pycache__中对应的.pyc缓存，迫使解释器重新编译。这一工具的注释里记录了此前sitecustomize.pymonkey-patch 方案失败的原因（site.getsitepackages()[0]指向的路径并非解释器优先搜索目录），属于很有价值的踩坑记录。

八、本地开发与调试

不部署 Manufact 时，可在本机直接运行：

# 安装依赖 npm install # 构建前端 Widget npm run build # 设置 token 并启动服务（默认端口 3002） HF_TOKEN=hf_yourtoken npm start

然后把任意 MCP 客户端指向http://localhost:3002/mcp。开发期如需热跟踪前端改动：

npm run dev

需要提醒的是：server.ts 中registerAppResource从dist/widget.html读取 HTML 提供服务，因此改过 src/mcp-app.ts 后必须先重新npm run build，否则 Claude 侧载入的仍是旧 Widget。

服务端还内置了两个供云平台/MCP 宿主健康探测的 HTTP 端点：GET /返回{ name: "FineTune Studio MCP", status: "ok", version: "1.0.0" }，GET /mcp返回{ name, status }；真正的 MCP JSON-RPC 走POST /mcp，内部基于 SDK 的StreamableHTTPServerTransport（启用enableJsonResponse，每个请求独立 session），body 大小限制为 10MB。

九、常见故障排查

README 汇总的高频问题按现象给出如下处置：

"AutoTrain Space not found in your HF account"未完成 AutoTrain Space 复制。按上文第 3.3 节操作，确保账号下存在名为autotrain-advanced的 Space（服务端正是按此固定名检索的）。

"HF_TOKEN environment variable is not set"服务端拿不到 token。到 Manufact 控制台服务的Settings → Environment Variables添加HF_TOKEN并重部署；本地运行则确认启动命令前已设置HF_TOKEN=...。源码中该错误信息由 server.ts 的hfPost/getHFToken抛出。

训练卡在 "Initializing" 超过 5 分钟AutoTrain 正在拉起 GPU 容器，首次运行需 3–5 分钟下载容器镜像。超过 10 分钟仍卡住，直接查看训练 Space 日志（路径你的用户名/autotrain-你的项目名）定位。

Inference Space 长时间 "building"3B+ 大模型在容器构建后还需要 5–10 分钟加载权重，可观察你的用户名/inference-你的项目名的构建进度。

模型回复乱码或跑题最常见原因是 Step 3 选择的 chat template 与训练数据格式不匹配：纯文本数据集选none，messages 格式数据集选tokenizer或具名模板。这也与前端在聊天模板下拉框下方的提示文案完全对应。

"Redeploy Space" 按钮当推理 Space 为空或 Gradio 应用无响应时，在训练完成面板点击Redeploy Space，服务端会以最新推理代码重新 commit 并触发重建——对应工具为deploy_inference_space。

十、技术栈小结

README 给出的分层技术栈可作为收尾索引：

若要更进一步，建议沿三条主线深入本仓库源码：一是 server.ts 中start_training的 PARAMS secret 注入与check_training_status的日志取证逻辑，理解"借第三方训练平台却仍能可靠感知任务状态"的通用思路；二是 server.ts 内嵌的推理 Space 模板与四级降级推理，理解 MCP 应用如何优雅应对 HF 推理生态的限制；三是 src/mcp-app.ts 中validateCustomData与defaultConfig，理解前端如何把复杂训练参数收敛为低门槛的表单交互。在此基础上，你可以把 FineTune Studio 的"模型微调 + 自动部署 + 对话验证"闭环改造成更适合自己业务的 Agent 工具。

【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub