Python 批量调用 AI API 改写商品标题:CSV 自动化、失败重试与断点续跑完整教程
电商商品标题需要批量优化?本文使用 Python、requests 与 uiuiAPI 的 Chat Completions 接口,开发可运行的 CSV 标题改写工具,支持 Excel 导入、环境变量密钥、失败重试、原子保存和断点续跑,详解 401/429 排错、计费估算与文案审核要点,适合电商运营和内容团队。
一、为什么要做一个批量改写工具?
运营团队经常遇到同一种工作:表格里有几百条商品标题,需要统一语气、删除冗余形容词、提升可读性,并保留品牌、规格和真实属性。人工逐条改写效率低;直接让模型处理整个大表,又容易遗漏某一行,出错后还得全部重来。
这次我们做一个逐行请求、逐行落盘的小工具。它读取 Excel 导出的 CSV,向 https://api.uiuihao.com/v1/chat/completions 发送每条标题,收到结果后立刻写回输出文件;途中断网或者账户余额不足时,下一次启动会跳过已成功完成的条目。它不是“一键保证销量”的 SEO 魔法,只负责生成可供人工审核的候选标题。
工作流程为:Excel/CSV → 读取行 → 计算唯一任务 ID → 调用 AI → 校验长度 → 原子写入 CSV → 人工复核。这一设计的好处是单条失败不会拖垮全部任务,也不会因为程序崩溃丢失已经保存的进度。
二、准备工作和接口选择
准备 Python 3.10 或更新版本,安装 requests 和 python-dotenv。打开 uiuiAPI 主站,登录后在控制台按实际界面创建 API Key,确认余额、分组、模型权限。uiuiAPI 是第三方模型聚合服务,并非 OpenAI 官方 API 服务;它的支持模型、渠道能力和计费以站内页面为准。
这里采用最常见的 Chat Completions 请求:model 决定路由,messages 给出系统约束与待处理标题。UIUI_MODEL 必须填写你在主站模型列表里实际可用、支持该接口的文本模型 ID,教程不硬编码一个可能没有权限的型号。
新建文件夹 csv-title-batch,目录如下:
csv-title-batch/
├── .env
├── .gitignore
├── input.csv
└── main.py
安装命令(Windows PowerShell):
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install "requests>=2.32,<3" "python-dotenv>=1,<2"
macOS / Linux 则使用:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'requests>=2.32,<3' 'python-dotenv>=1,<2'
.env 文件(不要提交到仓库):
UIUI_API_KEY=请填写你自己的密钥
UIUI_MODEL=请填写已开通的文本模型ID
.gitignore 内容:
.env
.venv/
__pycache__/
output.csv
将 Excel 文件“另存为 CSV UTF-8”,新建 input.csv,至少包含 sku、original_title、category 三列:
sku,original_title,category
A001,办公桌面收纳盒 大容量 多功能 超级好用,办公收纳
A002,不锈钢保温杯 500ml 简约日用,杯具
A003,棉质短袖T恤 经典纯色 日常,服饰
建议给每个 SKU 配上稳定编号。相同 SKU 如有不同原标题,程序会按不同任务处理,而不是误认为同一条。
三、可直接保存运行的完整 Python 代码
把下面内容保存为 main.py。代码限制单次最多读取 500 条;生产环境应按实际预算调小,先用 3 条样本确认输出质量。
import csv
import hashlib
import os
import random
import sys
import time
from pathlib import Path
import requests
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("UIUI_API_KEY", "").strip()
MODEL = os.getenv("UIUI_MODEL", "").strip()
API_URL = "https://api.uiuihao.com/v1/chat/completions"
INPUT = Path("input.csv")
OUTPUT = Path("output.csv")
FIELDS = ["task_id", "sku", "original_title", "rewritten_title", "status", "error"]
SYSTEM = (
"你是谨慎的中文电商编辑。只输出一行优化后的商品标题,不要说明。"
"保留原文已有的品牌、规格、材质、容量与可核实属性;"
"不新增功效、认证、销量、价格、促销承诺或虚构品牌;"
"尽量自然清晰,长度控制在8到45个汉字或字符。"
)
def task_id(row):
raw = "\0".join([row["sku"], row["original_title"], row["category"]])
return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:20]
def load_rows():
with INPUT.open("r", encoding="utf-8-sig", newline="") as f:
reader = csv.DictReader(f)
required = {"sku", "original_title", "category"}
if not required.issubset(set(reader.fieldnames or [])):
raise ValueError(f"input.csv 缺少列:{sorted(required)}")
rows = []
for row in reader:
cleaned = {k: (row.get(k) or "").strip() for k in required}
if cleaned["sku"] and cleaned["original_title"]:
rows.append(cleaned)
if len(rows) > 500:
raise ValueError("单次最多500条,请先拆分表格")
return rows
def load_progress():
if not OUTPUT.exists():
return {}
with OUTPUT.open("r", encoding="utf-8-sig", newline="") as f:
reader = csv.DictReader(f)
if reader.fieldnames != FIELDS:
raise ValueError("output.csv 表头与当前程序不一致,请先备份并处理")
return {row["task_id"]: row for row in reader}
def save_progress(data):
tmp = OUTPUT.with_suffix(".csv.tmp")
with tmp.open("w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(f, fieldnames=FIELDS)
writer.writeheader()
writer.writerows(data.values())
f.flush()
os.fsync(f.fileno())
os.replace(tmp, OUTPUT)
def rewrite_title(row):
payload = {
"model": MODEL,
"messages": [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": (
f"类目:{row['category']}\n原标题:{row['original_title']}"
)},
],
"stream": False,
}
headers = {"Authorization": f"Bearer {API_KEY}"}
for attempt in range(3):
try:
response = requests.post(
API_URL, headers=headers, json=payload, timeout=(5, 35)
)
if response.status_code in (429, 500, 502, 503, 504):
if attempt < 2:
time.sleep(min(2 ** attempt, 8) + random.random())
continue
response.raise_for_status()
data = response.json()
title = data["choices"][0]["message"]["content"]
if not isinstance(title, str):
raise ValueError("模型未返回文本内容")
title = title.strip().strip('"“”')
if "\n" in title or not 8 <= len(title) <= 60:
raise ValueError("标题为空、过长或包含多行,请人工复核")
return title
except (requests.Timeout, requests.ConnectionError):
if attempt < 2:
time.sleep(min(2 ** attempt, 8) + random.random())
continue
raise RuntimeError("网络超时或连接失败") from None
except requests.HTTPError as exc:
code = exc.response.status_code if exc.response is not None else "未知"
raise RuntimeError(f"HTTP {code},请检查密钥、权限或限流") from None
raise RuntimeError("达到重试上限")
def main():
if not API_KEY or not MODEL:
sys.exit("请在 .env 中填写 UIUI_API_KEY 和 UIUI_MODEL")
rows = load_rows()
progress = load_progress()
done = 0
for row in rows:
key = task_id(row)
if progress.get(key, {}).get("status") == "ok":
print(f"跳过已完成:{row['sku']}")
continue
result = {
"task_id": key,
"sku": row["sku"],
"original_title": row["original_title"],
"rewritten_title": "",
"status": "error",
"error": "",
}
try:
result["rewritten_title"] = rewrite_title(row)
result["status"] = "ok"
done += 1
print(f"完成:{row['sku']}")
except (RuntimeError, ValueError, KeyError, IndexError, requests.RequestException) as exc:
result["error"] = str(exc)[:120]
print(f"失败:{row['sku']},{result['error']}")
progress[key] = result
save_progress(progress)
print(f"本次新增成功 {done} 条,结果保存在 {OUTPUT}")
if __name__ == "__main__":
main()
四、执行与结果检查
激活虚拟环境后运行:
python main.py
预期输出示意(非实测,具体措辞由模型决定):
完成:A001
完成:A002
完成:A003
本次新增成功 3 条,结果保存在 output.csv
示意 CSV 中,A002 的候选标题可能为“500ml不锈钢保温杯 简约日常便携水杯”。这不是本轮真实生成的响应;读者必须核对“保温”“便携”等表述是否有商品依据,不能将模型输出直接当成产品事实。运行中如果某条失败,输出会记录 status=error。再次执行时只跳过 ok 的任务,从而继续未完成的部分。
这里有三个容易忽略的细节。首先,utf-8-sig 兼容 Excel 导出的 UTF-8 BOM,避免列名第一位出现不可见字符。其次,用 SKU、原标题和类目的哈希值作任务 ID,原标题发生变化会产生新任务。最后,每次更新借助临时文件和 os.replace 替换输出文件,在同一磁盘上降低写出半个 CSV 的风险。但仍应保留输入原件,不要在多个脚本进程中同时编辑同一个输出文件。
五、错误排查、费用与安全
401 Unauthorized: 令牌缺失、错误或失效,检查 .env 文件和主站控制台。403 Forbidden: 可能是账户或模型分组无权限,需查实际服务端提示。404 或模型不存在: 确认 UIUI_MODEL 与已启用渠道一致,并确认该模型支持 Chat Completions。429: 请求频率或配额受限,脚本只对短暂限流做有限重试;持续出现应降低速度。超时: 可能是网络或者上游生成慢,不能无限重试,尤其要注意请求已完成但响应丢失时存在重复计费风险。参数不兼容: 优先删除新增的可选参数,本例只发送基础字段;不同渠道对 system 消息的处理仍可能不同。
费用取决于模型、实际输入输出 Token、分组倍率和渠道定价,并不是“每处理一条免费”。可粗略估算为:总费用 ≈ 输入 Token 数 × 输入单价 + 输出 Token 数 × 输出单价,并按站内计费单位及倍率换算。批量任务最好先设账户预算、先测 3 条,再扩大到 30 条和全量;已经成功的条目不会自动重复提交,但错误重试可能产生额外费用。
API Key 必须保留在本地环境变量,不要粘贴到网页前端、截图、GitHub 或商品文件中。对含有客户手机号、地址、订单详情的表格,先脱敏再发送;此教程只用于不含个人敏感数据的商品文案。生产环境还需要结合库存、品牌法务规则做自动检测,避免模型生成未经证实的“官方”“最好”“100%有效”等广告用语。
六、可继续升级的方向
后续可以加“禁用词清单”和标题相似度去重,先用规则审核再让编辑确认;也能给每条候选标题记录人工评分,逐步优化提示词。若处理十万条以上,可把任务状态移入 SQLite 或数据库,提供队列、并发控制和预算阈值,而不是无限扩大一个 CSV。要进一步提高效率,还可以把程序封装成内部 Web 工具,但不要让浏览器直接持有 API Key。
总结
这个案例最重要的不是让模型改写一句标题,而是把 AI 调用包装成可中断、可检查、可恢复的业务流程。只要底层模型具备兼容的文本对话能力,代码就不依赖某个固定的热门模型名称。完成后先核对商品事实与价格承诺,再将结果导入电商后台。
资料与核实说明(2026-11-20):
- uiuiAPI 主站:https://api.uiuihao.com/
- uiuiAPI 模型广场示例页面(含
/v1/chat/completions接口提示):https://api.uiuihao.com/pricing/gpt-5.1-2025-11-13 - OpenAI Chat Completions 接口结构(仅用于兼容格式参考,非本站官方背书):https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create
- Requests 文档:https://requests.readthedocs.io/en/latest/
验证边界: 已核对公开接口路径与请求字段;未持有读者密钥,未在线调用、未测定真实模型输出、费用或成功率。不同模型和上游的兼容性需要读者自行验证。
暂无评论