# ArkTrain

**Repository Path**: leejersey/ark-train

## Basic Information

- **Project Name**: ArkTrain
- **Description**: 用火山方舟来训练是否认识空调的型号等相关信息
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔧 ArkTrain - 二手空调智能评估模型微调工具

> 基于火山引擎方舟平台的多模态大模型微调工具集，专注于二手空调图像识别与价值评估。

---

## 📖 目录

- [项目简介](#-项目简介)
- [系统架构](#-系统架构)
- [环境准备](#-环境准备)
- [快速开始](#-快速开始)
- [详细使用指南](#-详细使用指南)
- [文件说明](#-文件说明)
- [常见问题](#-常见问题)

---

## 🎯 项目简介

本项目是一套完整的**多模态大模型微调工作流**，用于训练一个能够：

- 🖼️ **识别空调图片** - 分析空调品牌、型号、外观成色
- 💰 **评估二手价值** - 根据图片和价格给出购买建议
- 💬 **专家式对话** - 模拟老师傅的专业分析口吻

### 工作流程概览

```mermaid
flowchart LR
    A[📊 CSV数据] --> B[🔄 trans.py<br>格式转换]
    B --> C[📤 upload_to_tos.py<br>图片上传]
    C --> D[☁️ TOS存储]
    D --> E[📝 upload_jsonl.py<br>JSONL上传]
    E --> F[🤖 方舟平台微调]
    F --> G[🧪 test_train.py<br>模型测试]
```

---

## 🏗️ 系统架构

### 核心组件

| 组件 | 文件 | 功能 |
|------|------|------|
| 数据转换器 | `trans.py` | CSV → JSONL 格式转换 |
| 图片上传器 | `upload_to_tos.py` | 下载图片并上传至 TOS |
| JSONL 上传器 | `upload_jsonl.py` | 修复格式并上传训练数据 |
| 连接测试器 | `test_tos_connection.py` | 诊断 TOS 连接问题 |
| 模型测试器 | `test_train.py` | 测试微调后的模型 |

### 技术栈

- **Python 3.8+**
- **火山引擎 TOS SDK** (`tos`) - 对象存储
- **火山引擎 Ark SDK** (`volcenginesdkarkruntime`) - 模型调用
- **Pandas** - 数据处理
- **python-dotenv** - 环境变量管理

---

## 🔧 环境准备

### 1. 安装 Python 依赖

```bash
pip install pandas tos python-dotenv volcenginesdkarkruntime requests
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并填入您的配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# ==================== 必填配置 ====================

# 火山引擎访问密钥 (从火山引擎控制台获取)
VOLC_ACCESS_KEY=AKXXXXXXXXXXXXXXXXXX
VOLC_SECRET_KEY=SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# TOS 存储桶名称 (需要先在控制台创建)
TOS_BUCKET_NAME=your-bucket-name

# ==================== 可选配置 ====================

# TOS 区域配置 (默认北京)
TOS_ENDPOINT=tos-cn-beijing.volces.com
TOS_REGION=cn-beijing

# 输入输出文件
INPUT_CSV=goofish-2026-01-16.csv
OUTPUT_JSONL=volc_multimodal_train.jsonl

# ==================== 模型测试配置 ====================

# 方舟平台 API Key (从方舟控制台获取)
ARK_API_KEY=your-ark-api-key

# 微调后的模型端点 ID
ENDPOINT_ID=ep-xxxxxxxxxxxxxxxx
```

### 3. 获取密钥说明

| 密钥 | 获取位置 |
|------|----------|
| `VOLC_ACCESS_KEY` / `VOLC_SECRET_KEY` | [火山引擎控制台](https://console.volcengine.com/iam/keymanage/) → IAM → 密钥管理 |
| `TOS_BUCKET_NAME` | [TOS 控制台](https://console.volcengine.com/tos/) → 创建存储桶 |
| `ARK_API_KEY` | [方舟控制台](https://console.volcengine.com/ark/) → API Key 管理 |
| `ENDPOINT_ID` | 方舟控制台 → 模型推理 → 接入点管理 |

---

## 🚀 快速开始

### 完整工作流（5 步完成微调）

```bash
# 步骤 1: 测试 TOS 连接
python test_tos_connection.py

# 步骤 2: 转换 CSV 数据为 JSONL (可选，用于本地预览)
python trans.py

# 步骤 3: 上传图片到 TOS 并生成训练数据
python upload_to_tos.py

# 步骤 4: 修复并上传 JSONL 文件
python upload_jsonl.py

# 步骤 5: 在方舟平台创建微调任务...
# (见下方详细指南)

# 步骤 6: 测试微调后的模型
python test_train.py test_ac.jpg
```

---

## 📚 详细使用指南

### 阶段一：数据准备

#### 1.1 准备 CSV 数据源

CSV 文件需包含以下列（以闲鱼爬取数据为例）：

| 列名 | 说明 | 示例 |
|------|------|------|
| `feeds-image--TDRC4fV1 src` | 商品图片 URL | `https://...jpg` |
| `main-title--sMrtWSJa` | 商品标题 | `格力 1.5P 变频空调` |
| `number--NKh1vXWM` | 价格 | `580` |
| `text--MaM9Cmdn` | 所在地 | `北京朝阳` |
| `cpv--R1RkOhUI` | 标签1 | `品牌：格力` |
| `cpv--R1RkOhUI (2)` | 标签2 | `成色：9成新` |
| `cpv--R1RkOhUI (3)` | 标签3 | `类型：变频` |

#### 1.2 运行数据转换（可选预览）

```bash
python trans.py
```

此脚本将 CSV 转换为火山引擎格式的 JSONL，生成 `volcengine_finetune_data.jsonl`。

> **注意**：此脚本生成的数据使用原始图片 URL，仅供本地预览。正式训练需使用 `upload_to_tos.py`。

---

### 阶段二：上传数据到 TOS

#### 2.1 测试 TOS 连接

首次使用请先测试连接：

```bash
python test_tos_connection.py
```

成功输出示例：

```
============================================================
火山引擎 TOS 连接测试
============================================================
✅ tos SDK 已安装，版本: 2.x.x
✅ TOS 客户端创建成功
✅ API 调用成功！找到 1 个存储桶:
   - your-bucket-name
✅ 上传测试成功！
✅ 测试文件已删除
============================================================
测试完成
============================================================
```

#### 2.2 上传图片并生成训练数据

```bash
python upload_to_tos.py
```

此脚本会：

1. 读取 CSV 中的图片 URL
2. 下载每张图片
3. 上传到 TOS 的 `images/` 目录
4. 生成使用 TOS 路径（`tos://bucket/path`）的 JSONL
5. 自动上传 JSONL 到 TOS 根目录

#### 2.3 上传修复后的 JSONL（如需）

如果之前的 JSONL 格式有问题，使用此脚本修复并重新上传：

```bash
python upload_jsonl.py
```

修复内容：
- `type: image` → `type: image_url`
- `image_url: "url"` → `image_url: {"url": "..."}`

---

### 阶段三：在方舟平台创建微调任务

1. 登录 [火山引擎方舟控制台](https://console.volcengine.com/ark/)

2. **创建数据集**
   - 进入「数据管理」→「数据集」
   - 新建数据集，类型选择「TOS」
   - 填入 TOS 路径：`tos://your-bucket/volc_multimodal_train.jsonl`

3. **创建微调任务**
   - 进入「模型训练」→「微调任务」
   - 选择基座模型（如 `doubao-vision-pro`）
   - 关联上一步创建的数据集
   - 配置训练参数（推荐默认）
   - 启动训练

4. **创建推理端点**
   - 训练完成后，进入「模型推理」→「接入点管理」
   - 基于微调模型创建端点
   - 记录端点 ID (`ep-xxxx`)

---

### 阶段四：测试微调模型

#### 4.1 配置端点 ID

在 `.env` 中添加：

```env
ARK_API_KEY=your-ark-api-key
ENDPOINT_ID=ep-xxxxxxxxxx
```

#### 4.2 运行测试

```bash
# 使用本地图片测试
python test_train.py test_ac.jpg

# 或使用任意空调图片
python test_train.py path/to/your/ac_image.jpg
```

成功输出示例：

```
🖼️ 使用本地图片: test_ac.jpg
🤖 空调专家正在看图...
📡 使用模型: ep-xxxxxxxxxx

💬 专家回复：
【物品识别】：这是一台格力1.5P变频空调...
【成色分析】：外观保持良好，约8-9成新...
【购买建议】：这个价格比较合理，建议确认制冷效果...
```

---

## 📁 文件说明

```
ArkTrain/
├── 📄 .env.example          # 环境变量模板
├── 📄 .env                  # 实际配置（需自行创建）
├── 📄 README.md             # 本文档
│
├── 🐍 trans.py              # CSV → JSONL 转换器（本地预览）
├── 🐍 upload_to_tos.py      # 图片上传 + 训练数据生成
├── 🐍 upload_jsonl.py       # JSONL 格式修复 + 上传
├── 🐍 test_tos_connection.py # TOS 连接诊断
├── 🐍 test_train.py         # 微调模型测试
│
├── 📊 goofish-2026-01-16.csv           # 示例 CSV 数据
├── 📝 volcengine_finetune_data.jsonl   # trans.py 输出
├── 📝 volc_multimodal_train.jsonl      # upload_to_tos.py 输出
│
└── 🖼️ test_ac.jpg           # 测试用空调图片
```

### 脚本详情

#### `trans.py` - 数据格式转换器

- **输入**：CSV 文件（闲鱼商品数据）
- **输出**：`volcengine_finetune_data.jsonl`
- **特点**：保留原始图片 URL，适合本地预览数据格式
- **生成内容**：自动根据价格生成购买建议话术

#### `upload_to_tos.py` - 完整数据处理管道

- **输入**：CSV 文件
- **输出**：
  - TOS 上的图片（`images/` 目录）
  - 本地 + TOS 上的 JSONL 文件
- **特点**：
  - 下载原图并重新上传至 TOS
  - 生成 `tos://` 格式的图片路径
  - 自动上传训练数据

#### `upload_jsonl.py` - JSONL 修复上传器

- **功能**：修复常见的格式问题并上传
- **修复项**：
  - `type: image` → `type: image_url`
  - 简单字符串 URL → 对象格式 `{"url": "..."}`

#### `test_tos_connection.py` - 连接诊断工具

- **测试项**：
  1. SDK 安装检查
  2. 客户端创建
  3. 列出存储桶
  4. 上传/删除测试文件

#### `test_train.py` - 模型测试工具

- **输入**：本地图片路径
- **功能**：
  - 图片转 Base64
  - 调用微调后的模型 API
  - 支持自动重试（应对 429 错误）

---

## ❓ 常见问题

### Q1: SignatureDoesNotMatch 错误

**原因**：AK/SK 配置错误或有多余空格

**解决方案**：
1. 运行 `python test_tos_connection.py` 诊断
2. 检查 `.env` 中的 AK/SK 是否有多余空格
3. 确认密钥是否正确复制

### Q2: 图片下载失败

**原因**：原图 URL 有防盗链或已失效

**解决方案**：
- 脚本已添加 User-Agent 伪装
- 失败的图片会被跳过，不影响整体流程

### Q3: 模型返回 429 错误

**原因**：API 调用频率超限

**解决方案**：
- `test_train.py` 已内置重试机制
- 如持续出错，请稍后再试

### Q4: JSONL 格式验证失败

**原因**：图片类型格式不符合要求

**解决方案**：
- 运行 `python upload_jsonl.py` 自动修复
- 确保使用 `image_url` 类型而非 `image`

### Q5: 如何添加更多训练数据？

1. 准备新的 CSV 文件
2. 修改 `.env` 中的 `INPUT_CSV` 变量
3. 重新运行 `python upload_to_tos.py`
4. 在方舟平台更新数据集

---

## 📝 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| v1.0 | 2026-01-16 | 初始版本，完整工作流 |

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

---

## 📄 许可证

MIT License

---

> 💡 **提示**：如有问题，请先运行 `test_tos_connection.py` 进行诊断。