RobertCazacu/Propel
GitHub: RobertCazacu/Propel
一款面向跨境电商卖家的产品数据自动化处理工具，通过规则引擎和 AI 增强自动修正多平台商品分类错误并补全缺失属性。
Stars: 1 | Forks: 0
# Marketplace Offer Processor
一个基于 Streamlit 的内部工具，用于自动修正跨多个电商平台的产品 Offer 错误 —— 包括 eMAG Romania、eMAG HU、eMAG BG、Trendyol、Allegro、Decathlon、Pepita、FashionDays 等。
## 功能概述
从电商平台获取 Offer 导出文件，并自动修复以下问题：
| 错误代码 | 含义 | 处理方式 |
|---|---|---|
| **1007** | 缺失或错误的分类 | 通过关键词规则或 AI 批量分类解决 |
| **1009** | 缺失必填特性 | 通过规则 + AI 填充 |
| **1010** | 无效的特性值 | 移除并重新填充 |
## 功能特性
- **多电商平台支持** —— 每个平台都有独立且以 Parquet 格式存储的参考数据（分类、特性、允许值）
- **基于规则的分类映射** —— 支持 AND 逻辑的关键词规则、排除词及特异性排序
- **AI 批量分类** —— 每次 API 调用最多分类 60 个产品；自动从 AI 决策中学习规则
- **AI 特性填充** —— 填充缺失的必填字段；适配各平台语言（罗马尼亚语、匈牙利语、保加利亚语、波兰语等）
- **多提供商 LLM** —— 可在 UI 或 `.env` 中切换 Anthropic、Ollama、Gemini、Groq 或 Mistral，无需重启
- **预处理成本估算** —— 处理开始前显示预估 Token 用量和 USD 成本
- **持久化 AI 缓存** —— 已处理的产品会被缓存；重复运行消耗零 Token
- **颜色标记的 Excel 导出** —— 每种类型的更改使用不同颜色
- **公网访问** —— Cloudflare Tunnel + 启动时 Telegram Bot 通知
## 项目结构
```
marketplace_tool/
├── app.py # Streamlit entry point
├── start_all.py # Auto-start: Streamlit + Cloudflare Tunnel + Telegram
├── .env.example # Environment variable template
├── requirements.txt
│
├── core/
│ ├── ai_enricher.py # AI enrichment with persistent cache; delegates to LLMRouter
│ ├── llm_router.py # Singleton LLM router — single access point for all AI calls
│ ├── loader.py # Loads categories / characteristics / values from Parquet
│ ├── processor.py # Rule-based + AI processing pipeline
│ ├── offers_parser.py # Parses marketplace offer export files
│ ├── exporter.py # Generates color-coded Excel output
│ ├── state.py # Session state + persistent statistics
│ ├── templates.py # Excel template generators for reference files
│ ├── app_logger.py # Centralized logger
│ ├── logger.py # Processing logs with 7-day auto-cleanup
│ ├── ai_logger.py # AI request/response logger (24h retention)
│ ├── vision/
│ │ ├── __init__.py # Exports analyze_product_image, ImageAnalysisResult
│ │ ├── image_analyzer.py # Main orchestrator for image-based attribute extraction
│ │ ├── color_analyzer.py # Algorithmic color detection (PIL quantize, HSV classification)
│ │ ├── image_fetcher.py # Image downloader with local cache (data/image_cache/)
│ │ ├── visual_provider.py # Vision model providers (Ollama llava-phi3, Mock)
│ │ └── visual_rules.py # JSON rules engine (data/visual_rules.json)
│ └── providers/
│ ├── base.py # Abstract BaseLLMProvider
│ ├── anthropic_provider.py # Anthropic Claude (SDK)
│ ├── ollama_provider.py # Ollama local models (REST)
│ ├── gemini_provider.py # Google Gemini (REST)
│ ├── groq_provider.py # Groq (REST, OpenAI-compatible)
│ └── mistral_provider.py # Mistral AI (REST, OpenAI-compatible)
│
├── pages/
│ ├── dashboard.py # Metrics dashboard + run history
│ ├── setup.py # Load marketplace reference files
│ ├── process.py # Process offers (rules + AI)
│ ├── results.py # View results + export Excel
│ ├── diagnostic.py # System diagnostic
│ └── llm_providers.py # AI provider management (switch, configure, test)
│
└── data/
├── eMAG_Romania/
│ ├── categories.parquet
│ ├── characteristics.parquet
│ └── values.parquet
├── eMAG_HU/ # eMAG Hungary
├── eMAG_BG/ # eMAG Bulgaria
├── Trendyol/
├── FashionDays/
├── FashionDays_BG/
├── ai_cache.json # Persistent AI cache (gitignored)
├── dashboard_stats.json # Cumulative statistics (gitignored)
├── visual_rules.json # Image analysis rules (color thresholds, per-category overrides)
├── logs/ # Processing logs, 7-day retention (gitignored)
├── ai_logs/ # AI request/response logs, 24h retention (gitignored)
└── image_cache/ # Downloaded product images, persistent (gitignored)
```
## 安装
```
git clone https://github.com/your-username/marketplace-tool.git
cd marketplace-tool
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env 并填入你的 API keys
streamlit run app.py
```
应用将在 `http://localhost:8501` 打开。
## 使用说明
### 步骤 1 — 配置 Marketplace
1. 进入 **⚙️ Setup Marketplace**
2. 选择或添加一个 Marketplace
3. 上传 3 个参考 Excel 文件：
- **Categories** (`emag_categories.xlsx`) —— 列：`id`、`name`、`parent_id`
- **Characteristics** (`emag_characteristics.xlsx`) —— 列：`id`、`category_id`、`name`、`mandatory`
- **Allowed values** (`characteristic_values.xlsx`) —— 列：`emag_characteristic_id`、`value`
4. 点击 **Save** —— 数据将以 Parquet 格式在本地存储，无需重复上传
### 步骤 2 — 配置 AI Provider（可选）
1. 进入 **🤖 LLM Providers**
2. 选择一个提供商并输入 API Key
3. 点击 **Activate** —— 立即生效，无需重启
如果没有配置 AI Provider，工具仍可仅使用规则运行。
### 步骤 3 — 处理 Offer
1. 进入 **📁 Process Offers**
2. 选择已配置的 Marketplace（活跃 Marketplace 横幅显示统计信息）
3. 上传来自平台的 Offer 导出文件
4. （可选）添加或编辑分类映射规则
5. 展开 **AI Cost Estimate** 预览 Token 用量和 USD 成本
6. 点击 **Start processing for [Marketplace]**
### 步骤 4 — 结果与导出
1. 进入 **📊 Results**
2. 查看已处理的产品
3. 点击 **Generate corrected Excel** 并下载
## Excel 导出颜色
| 颜色 | 含义 |
|---|---|
| 绿色 | 自动添加的新特性 |
| 蓝色 | 已分配分类（错误 1007） |
| 橙色 | 已修正分类 |
| 红色 | 已移除无效值 |
| 黄色 | 需要手动补全 |
## AI —— 多提供商系统
该应用支持 5 个 AI 提供商，并提供统一的接口。所有提供商接受相同的 Prompt 格式 —— 切换时无需修改其他代码。
### 可用提供商
| Provider | Default model | 备注 |
|---|---|---|
| **anthropic** | `claude-haiku-4-5-20251001` | 推荐 —— 质量/成本比最佳 |
| **ollama** | `qwen2.5:14b` | 免费，本地运行 —— 需要运行 `ollama serve` |
| **gemini** | `gemini-2.0-flash` | Google —— 提供免费额度 |
| **groq** | `llama-3.3-70b-versatile` | 免费，有速率限制，速度极快 |
| **mistral** | `mistral-small-latest` | Mistral AI |
### 切换提供商
**通过 UI：** 进入 **🤖 LLM Providers** → 点击任意提供商的 **Activate**。
**通过 `.env`**（需要重启）：
```
ACTIVE_PROVIDER=groq
```
**运行时**（无需重启）：
```
from core.llm_router import switch_provider
switch_provider("groq")
```
### Marketplace 语言支持
AI Prompt 会自动包含对应 Marketplace 的语言上下文：
| Marketplace | AI 语言 |
|---|---|
| eMAG Romania | 罗马尼亚语 |
| eMAG HU | 匈牙利语 |
| eMAG BG | 保加利亚语 |
| Allegro | 波兰语 |
| Trendyol / Decathlon / Pepita / FashionDays | 中立 |
### AI 请求/响应日志
每次 AI 调用都会保存到 `data/ai_logs/YYYY-MM-DD.json`（24 小时后自动删除）。
每条记录包含：
| 字段 | 描述 |
|---|---|
| `timestamp` | 精确到毫秒的 ISO 时间戳 |
| `type` | `category_batch`、`char_enrichment` 或 `image_analysis` |
| `provider` / `model` | 当前使用的提供商和模型名称 |
| `marketplace` | 正在处理的 Marketplace |
| `duration_ms` | 以毫秒为单位的响应时间 |
| `request.offer_id(s)` | 相关的 Offer ID |
| `request.prompt` | 发送给 AI 的完整 Prompt |
| `request.products` / `request.missing_characteristics` | 完整的输入数据 |
| `response.raw` | AI 返回的原始文本 |
| `response.parsed` | 从响应中解析的 JSON |
| `results` | 每个 Offer 最终接受的值 |
| `stats.accepted` / `stats.rejected` | 接受/拒绝值的计数 |
日志文件位置：`data/ai_logs/`（gitignored —— 仅限本地）。
### Token 优化
| 优化项 | 节省 |
|---|---|
| 批量分类（N 个产品 = 1 次 API 调用） | ~97% |
| 持久化缓存（已见产品 = 0 Token） | 重复运行时 100% |
| 仅对缺失的必填字段使用 AI | ~50% |
| 从 AI 决策自动学习规则 | 随时间推移 100% |
### 预处理成本估算
开始之前，展开 **AI Cost Estimate** 查看：
- 需要 AI 进行分类的产品数量
- 批次数
- 需要 AI 填充特性的产品数量
- **预估总成本（USD）**
基于 `claude-haiku-4-5-20251001` 定价：输入 $0.80/MTok，输出 $4.00/MTok。
## 分类映射规则
规则优先于 AI 执行 —— 命中规则消耗零 Token。
```
{"keywords": "sneaker, men", "exclude": "kids", "category": "Men's Sport Shoes"}
```
| 字段 | 描述 |
|---|---|
| `keywords` | 逗号分隔的单词 —— **所有**单词必须出现在产品标题中（AND 逻辑，不区分大小写） |
| `exclude` | 必须**不**出现在标题中的单词（可选） |
| `category` | 来自 Marketplace 参考数据的确切分类名称 |
关键词越多的规则优先检查（越具体 = 优先级越高）。
向后兼容旧格式：`{"prefix": "...", "category": "..."}`。
## 公网访问 —— Cloudflare Tunnel + Telegram
该应用可以通过免费的 Cloudflare Tunnel 公开暴露，无需 VPN。
### 工作原理
1. PC 启动 → Windows Task Scheduler 在登录时运行 `start_all.py`
2. `start_all.py` 启动 Streamlit + Cloudflare Tunnel
3. 新的公网 URL 会在约 15 秒内通过 **Telegram** 自动发送
4. 可从任何地方访问 —— 无需 VPN
### 配置（`.env`）
```
TELEGRAM_TOKEN=your-bot-token # from @BotFather on Telegram
TELEGRAM_CHAT_ID=your-chat-id # from api.telegram.org/botTOKEN/getUpdates
STREAMLIT_PORT=8501 # optional, default 8501
```
### 安装 Task Scheduler（以管理员身份运行 PowerShell）
```
$action = New-ScheduledTaskAction `
-Execute "python" `
-Argument "C:\Users\manue\Desktop\marketplace_tool\start_all.py" `
-WorkingDirectory "C:\Users\manue\Desktop\marketplace_tool"
$trigger = New-ScheduledTaskTrigger -AtLogon
$settings = New-ScheduledTaskSettingsSet `
-ExecutionTimeLimit (New-TimeSpan -Hours 0) `
-RestartCount 3 `
-RestartInterval (New-TimeSpan -Minutes 2)
Register-ScheduledTask `
-TaskName "MarketplaceTool" `
-Action $action `
-Trigger $trigger `
-Settings $settings `
-RunLevel Highest `
-Force
```
## 环境变量参考
| 变量 | 必填 | 默认值 | 描述 |
|---|---|---|---|
| `ACTIVE_PROVIDER` | 否 | `anthropic` | 当前 LLM 提供商 |
| `ANTHROPIC_API_KEY` | 如果使用 Anthropic | — | Anthropic API Key |
| `ANTHROPIC_MODEL` | 否 | `claude-haiku-4-5-20251001` | Claude 模型 |
| `OLLAMA_BASE_URL` | 如果使用 Ollama | `http://localhost:11434` | Ollama 服务器 URL |
| `OLLAMA_MODEL` | 否 | `qwen2.5:14b` | Ollama 模型名称 |
| `GEMINI_API_KEY` | 如果使用 Gemini | — | Google Gemini API Key |
| `GEMINI_MODEL` | 否 | `gemini-2.0-flash` | Gemini 模型 |
| `GROQ_API_KEY` | 如果使用 Groq | — | Groq API Key |
| `GROQ_MODEL` | 否 | `llama-3.3-70b-versatile` | Groq 模型 |
| `MISTRAL_API_KEY` | 如果使用 Mistral | — | Mistral API Key |
| `MISTRAL_MODEL` | 否 | `mistral-small-latest` | Mistral 模型 |
| `TELEGRAM_TOKEN` | 否 | — | Telegram Bot Token |
| `TELEGRAM_CHAT_ID` | 否 | — | Telegram Chat ID |
| `STREAMLIT_PORT` | 否 | `8501` | Streamlit 端口 |
## 常用命令
```
# 正常启动
streamlit run app.py
# 完整启动 (Streamlit + Tunnel + Telegram notification)
python start_all.py
# 一次性 values.xlsx → Parquet 转换
python fix_values_parquet.py
# 检查 Parquet 文件
python -c "import pandas as pd; df=pd.read_parquet('data/eMAG_Romania/values.parquet'); print(df.shape)"
```
## 更新日志
### v5 — 2026-03-22
- **基于图像的颜色检测** —— 新增 `core/vision/` 包；以算法方式分析产品图像（使用 Pillow + PIL quantize，无需 ML）
- `image_fetcher.py` —— 根据 URL 哈希下载并缓存图像到 `data/image_cache/`
- `color_analyzer.py` —— 基于角点的背景移除、PIL FASTOCTREE 量化、中性色规避、HSV 色系分类（Negru, Alb, Gri, Rosu, Albastru, Verde, Mov, Roz, Portocaliu, Galben, Maro, Bej, Turcoaz, Visiniu, Kaki, Bleumarin, Multicolor），针对 Photoroom 图像的白色产品快捷检测
- `visual_provider.py` —— 可选 Ollama 视觉模型集成（`llava-phi3`），用于产品类型提示
- `visual_rules.py` —— 基于 JSON 的规则引擎（`data/visual_rules.json`），支持按分类覆盖
- `image_analyzer.py` —— 主编排器；将图像结果合并到 `new_chars` 而不修改现有的文本流程
- **图像分析 UI** —— Process Offers 中新增两个复选框："Detectează culoarea din imagine" 和 "Folosește imaginea pentru îmbunătățirea categoriei"
- **图像分析日志** —— `ai_logger.py` 中新增 `log_image_analysis()`；每次图像分析（无论成功或失败）作为 `image_analysis` 类型记录到每日 AI 日志
- **修复：Marketplace 语言上下文** —— `_mp_ctx()` 使用 `_MP_ALIASES` 列表重写，支持完全宽松匹配：`BG`、`bg`、`Bulgaria`、`BGN`、`HU`、`Hungary`、`Ungaria`、`HUF`、`PL`、`Polonia`、`Allegro`、`FashionDays BG/HU` 等
- **修复：白色产品检测** —— 正确检测白色背景上的 Photoroom 图像为 "Alb"，而非 "Rosu" 或 "Bej"
- **修复：逗号分隔的图像 URL** —— `Imagini` 列可能包含多个 URL；仅使用第一个 URL 进行分析
- **修复：`Imagini` 列别名** —— 向 `offers_parser.py` 图像 URL 别名添加了 `"imagini"` 和 `"image src"`
- **`requirements.txt`** —— 添加了 `Pillow>=10.0.0`、`requests>=2.28.0`、`numpy>=1.24.0`
- **`.gitignore`** —— 添加了 `data/image_cache/`
### v4 — 2026-03-22
- **AI 请求/响应日志记录器** —— 每次 AI 调用保存到 `data/ai_logs/YYYY-DD.json`，保留 24 小时；记录完整 Prompt、原始响应、解析结果、duration_ms、offer_id、提供商、模型、接受/拒绝计数
- `core/ai_logger.py` —— 新模块：`log_category_batch()`、`log_char_enrichment()`、`AICallTimer`、`list_ai_log_files()`、`read_ai_log()`；每次写入时自动清理
- `ai_enricher.py` —— 集成计时（`time.perf_counter`）并在每次 `get_router().complete()` 后记录日志
- `processor.py` —— `process_product()` 接受 `offer_id` 参数，传递给 `enrich_with_ai` → logger
- `pages/process.py` —— 将 `offer_id` 传递给 `process_product()`
- `.gitignore` —— 添加了 `data/ai_logs/`
### v3 — 2026-03-21
- **修复：eMAG HU / BG 在 AI 中使用了罗马尼亚语上下文** —— `_mp_ctx()` 子串匹配按键长度降序排序；添加了明确的 `emag_hu`（匈牙利语）和 `emag_bg`（保加利亚语）条目；自由格式 Prompt 更新为使用 Marketplace 本地语言
- **UI：Process Offers 中的活跃 Marketplace 横幅** —— 选择 Marketplace 后显示名称、分类计数、特性计数、值计数
- **AI 成本估算器** —— 预处理估算 Token 批次、特性调用和 USD 成本
- **多提供商 LLM 架构** —— `core/providers/` 包含抽象 `BaseLLMProvider` + 5 个提供商；`core/llm_router.py` 单例，包含 `get_router()`、`switch_provider()`、`reset_router()`
- **`ai_enricher.py` 重构** —— 移除直接的 Anthropic 依赖；所有调用通过 `get_router().complete()` 进行
- **LLM Providers 页面** —— 用于配置、切换和测试所有提供商的完整 UI；直接写入 `.env`
- **`start_all.py` 安全加固** —— Telegram 凭据从硬编码移至 `.env`
- **添加了 `.gitignore` 和 `.env.example`**
### v2 — 2026-03-20
- AI Prompt 中的动态 Marketplace 上下文（`_mp_ctx()`）
- 将所有分类发送给 AI（移除了 250 分类限制）
- 自动学习品牌过滤器（从关键词规则中排除全大写 Token 和型号代码）
- 通过 Cloudflare Tunnel 公网访问 + 启动时 Telegram 通知
- Windows Task Scheduler 自动启动
### v1 —— 初始版本
- 核心处理管道：分类映射、特性填充、值验证
- 具有 AND 逻辑关键词的基于规则的引擎
- Claude AI 集成，支持持久化缓存和批量分类
- 颜色标记的 Excel 导出
- 带有持久化累积统计的仪表板
标签：AI数据增强, AI风险缓解, Allegro, Anthropic API, API密钥扫描, Claude大模型, eMAG, Excel数据处理, Kubernetes, LLM评估, LLM集成, Mistral, Ollama, Parquet格式, Python开发, Streamlit应用, Telegram机器人, Trendyol, 云flare隧道, 云计算, 内部工具, 商品信息优化, 商品映射, 商品缺失补全, 多平台管理, 多语言处理, 数据清洗, 本地大模型, 电商运营, 自动化分类, 规则引擎, 跨境电商, 逆向工具