电商工单处理全流程:从rag规则减速-到检测-到标注
电商工单处理全流程:从检测到标注
包含每一次的提示词构造、知识库的具体打分计算以及最终结果。
📋 前置准备:模拟数据
为了演示方便,我们先约定好以下模拟数据(真实运行时这些来自文件):
1. 待处理的工单(Excel里的一行)
| field_num (工单号) | conversation (对话内容) |
|---|---|
| GD-2025-001 | “客服你好,我昨天在商城买的PLA耗材还没发货,帮我查一下订单状态,什么时候能发?” |
2. 电商知识库 (rag/e-com.json,简化为2条)
[
{
"tag_id": "EC001",
"level3_tag": "订单发货查询",
"official_definition": "用户询问订单是否发货、物流快递状态、预计发货或送达时间",
"search_keywords": ["发货", "物流", "快递", "什么时候发", "订单状态"],
"common_examples": ["我的订单发货了吗", "帮我查一下物流", "什么时候能发货"],
"priority": "high"
},
{
"tag_id": "EC002",
"level3_tag": "耗材质量问题",
"official_definition": "用户反馈购买的耗材(如PLA、ABS)有质量瑕疵",
"search_keywords": ["断料", "耗材", "质量差", "有气泡"],
"common_examples": ["这个耗材质量不好"],
"priority": "normal"
}
]
3. 提示词模板 (简化版)
- 类型检测提示词 (
promptTicketTypeDetection.txt):“请判断以下工单属于哪个类型:[AMS, P2S, E-COMMERCE, FILAMENT, …]。只返回JSON,包含 type 和 reason 字段。”
- 电商标注提示词 (
promptIntentClassifyGongDanE-commerce.txt):“你是电商工单标注员。请根据对话内容提取核心信息并分类。返回JSON格式,包含:核心信息、分类结果集(一级、二级、三级标签、置信得分、分类依据)。”
🚀 开始执行流程
流程 0:初始化
代码加载 JSON 知识库到内存,初始化 Gemini 客户端。
- 结果:
ecommerce_knowledge_base对象就绪,包含了上面那 2 条 JSON 数据。
流程 1:第一次 LLM 调用 —— 检测工单类型
代码调用 detect_ticket_type 函数。
1.1 构造的提示词 (Full Prompt):
请判断以下工单属于哪个类型:[AMS, P2S, E-COMMERCE, FILAMENT, STUDIO, HANDY, MAKERWORLD, NONSENSE, UNKNOWN]。只返回JSON,包含 type 和 reason 字段。
【工单对话数据】:客服你好,我昨天在商城买的PLA耗材还没发货,帮我查一下订单状态,什么时候能发?
1.2 LLM 返回结果:
{
"type": "E-COMMERCE",
"reason": "用户提及了‘商城’、‘买的’、‘订单状态’,属于电商购物咨询场景。"
}
- 代码动作:解析出
ticket_type = "E-COMMERCE"。因为是电商,触发硬编码规则:必须调用知识库。
流程 2:知识库匹配与打分 (核心逻辑)
代码执行 ecommerce_knowledge_base.build_context_for_dialog(...)。
2.1 输入 Query:
“客服你好,我昨天在商城买的PLA耗材还没发货,帮我查一下订单状态,什么时候能发?”
2.2 开始计算 (_score_entry):
代码遍历内存中的 2 条条目,分别打分。
🧮 计算条目 1 (EC001: 订单发货查询)
- 三级标签:“订单发货查询” 不全在问句里,但问句有"发货"。代码逻辑是看整个标签串,这里没完全匹配,+0分。
- 关键词 (
search_keywords):- “发货” 在问句里 -> +3.0
- “订单状态” 在问句里 -> +3.0
- 小计:+6.0
- 官方定义:拆词后 “订单”、“发货”、“状态” 匹配 -> +3.0
- 典型问法:“什么时候能发货” 是相似问法 -> +5.0
- 基础总分:0 + 6 + 3 + 5 = 14.0
- 优先级加成:
priority是high,乘以 1.12。 - 最终得分 (EC001):14.0×1.12=15.6814.0 \times 1.12 = \mathbf{15.68}14.0×1.12=15.68
🧮 计算条目 2 (EC002: 耗材质量问题)
- 关键词:只有"耗材"匹配 -> +3.0
- 其他项:均不匹配。
- 优先级:
normal,不加成。 - 最终得分 (EC002):3.0\mathbf{3.0}3.0
2.3 排序与格式化:
- 排序结果:EC001 (15.68) > EC002 (3.0)。
- 代码调用
format_entries,生成一段文本。
2.4 知识库输出结果 (RAG Context):
[1] tag_id=EC001 三级标签:订单发货查询(匹配度参考分:15.68)
官方定义:用户询问订单是否发货、物流快递状态、预计发货或送达时间
关键词:发货、物流、快递、什么时候发、订单状态
典型问法:我的订单发货了吗;帮我查一下物流;什么时候能发货
[2] tag_id=EC002 三级标签:耗材质量问题(匹配度参考分:3.00)
官方定义:用户反馈购买的耗材(如PLA、ABS)有质量瑕疵
关键词:断料、耗材、质量差、有气泡
典型问法:这个耗材质量不好
流程 3:第二次 LLM 调用 —— 具体标注
代码调用 call_classify_llm,将上面的知识库文本拼接到提示词里。
3.1 构造的最终提示词 (Full Prompt):
你是电商工单标注员。请根据对话内容提取核心信息并分类。返回JSON格式,包含:核心信息、分类结果集(一级、二级、三级标签、置信得分、分类依据)。
【知识库检索参考】(仅辅助对齐三级标签命名与业务含义,最终以工单原文与分类体系为准):
[1] tag_id=EC001 三级标签:订单发货查询(匹配度参考分:15.68)
官方定义:用户询问订单是否发货、物流快递状态、预计发货或送达时间
关键词:发货、物流、快递、什么时候发、订单状态
典型问法:我的订单发货了吗;帮我查一下物流;什么时候能发货
[2] tag_id=EC002 三级标签:耗材质量问题(匹配度参考分:3.00)
官方定义:用户反馈购买的耗材(如PLA、ABS)有质量瑕疵
... (省略)
【工单对话数据】:客服你好,我昨天在商城买的PLA耗材还没发货,帮我查一下订单状态,什么时候能发?
3.2 LLM 返回结果:
{
"核心信息": {
"核心故障现象": "用户咨询订单未发货",
"强关联关键信息": ["PLA耗材", "未发货", "订单状态"],
"涉及电商核心场景/模块": "订单物流",
"工单场景": "商城购物后咨询发货",
"客服故障定位结论": "需查询订单物流状态"
},
"分类结果集": [
{
"一级标签": "电商咨询",
"二级标签": "订单问题",
"三级标签": "订单发货查询",
"四级标签": "",
"置信得分": 0.98,
"分类依据": "用户明确询问发货时间和订单状态,完全匹配知识库EC001定义。"
}
]
}
流程 4:结果整理与保存
代码将 LLM 返回的 JSON 解析,填入 Excel 的列中:
- 工单类型:
E-COMMERCE - 模型输出一级标签:
电商咨询 - 模型输出三级标签:
订单发货查询 - 分类置信得分:
0.98 - 处理状态:
成功
最后写入 CSV 缓存和最终 Excel。
from google import genai
from google.oauth2 import service_account
from google.genai import types
import os
import json
import pandas as pd
import logging
import time
from concurrent.futures import ThreadPoolExecutor, as_completed
import threading
import json_repair
from typing import Dict, List, Optional, Tuple
# ======================== 基础配置 ========================
# 脚本所在目录,用于解析相对路径(知识库 JSON 等)
_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
MAX_WORKER_THREADS = 100 # 线程数,根据服务器性能调整
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(levelname)s - %(message)s',
handlers=[logging.StreamHandler()]
)
# 文件路径配置(请根据实际业务修改)
EXCEL_INPUT_PATH = r"./data/ticket_general.1k.csv" # 输入:工单Excel文件
EXCEL_OUTPUT_PATH = r"./data/p2s工单标签结果_最终.xlsx" # 输出:标注结果Excel
CSV_TEMP_CACHE = r"./data/p2s工单_temp_results_cache.csv" # 临时缓存:防止程序中断丢失数据
CRED_JSON_PATH = r"./google-credential.json" # Google服务账号密钥文件
CLASSIFY_PROMPT_FILE_P2S = r"./templates/promptIntentClassifyGongDanP2S.txt" # P2S专属标注提示词模板
CLASSIFY_PROMPT_FILE_AMS = r"./templates/promptIntentClassifyGongDanAms.txt" # AMS专属标注提示词模板
CLASSIFY_PROMPT_FILE_ECOMMERCE = r"./templates/promptIntentClassifyGongDanE-commerce.txt" # 电商专属标注提示词模板
CLASSIFY_PROMPT_FILE_FILAMENT = r"./templates/promptIntentClassifyGongDanHaoCai.txt" # 耗材专属标注提示词模板
CLASSIFY_PROMPT_FILE_STUDIO = r"./templates/promptIntentClassifyGongDanStudio.txt" # Studio专属标注提示词模板
CLASSIFY_PROMPT_FILE_HANDY = r"./templates/promptIntentClassifyGongDanHandy.txt" # Handy专属标注提示词模板
CLASSIFY_PROMPT_FILE_MAKERWORLD = r"./templates/promptClassifyMW.txt" # MakerWorld专属标注提示词模板
TICKET_TYPE_DETECTION_PROMPT = r"./templates/promptTicketTypeDetection.txt" # 工单类型检测提示词
RAG_ECOMMERCE_JSON = os.path.join(_SCRIPT_DIR, "rag", "e-com.json") # 电商三级标签 RAG 知识库
# 数据处理配置
MAX_DATA_SIZE = 10 # -1表示使用全部数据,其他正数表示处理的最大数据量
# Excel列名配置(需与输入Excel列名完全一致)
DIALOG_COLUMN = "conversation"
WORK_ORDER_ID_COLUMN = "field_num" # 工单号列名配置
Printer_Model = "printermodel"
# LLM模型配置(Google Gemini)
PROJECT_ID = "gen-lang-client-0167357249" # Google Cloud项目ID
MODEL_NAME = "gemini-3-flash-preview"
# 线程锁:保证多线程写CSV的安全性
file_save_lock = threading.Lock()
class ECommerceKnowledgeBase:
"""
基于 rag/e-com.json 的轻量检索:按工单文本与 search_keywords、三级标签、示例句重叠打分,
供电商工单分类时注入参考,以及 Agent 工具 query_ecommerce_knowledge 查询。
"""
def __init__(self, json_path: str):
self._path = json_path
self._entries: List[dict] = []
self._load()
def _load(self) -> None:
if not os.path.isfile(self._path):
logging.warning(f"电商知识库文件不存在,RAG 将为空:{self._path}")
return
try:
with open(self._path, "r", encoding="utf-8") as f:
data = json.load(f)
if isinstance(data, list):
self._entries = data
else:
self._entries = []
logging.info(f"已加载电商知识库 {len(self._entries)} 条:{self._path}")
except Exception as e:
logging.error(f"加载电商知识库失败:{e}")
self._entries = []
def reload(self) -> None:
self._load()
def _score_entry(self, query: str, entry: dict) -> float:
q_lower = query.lower()
score = 0.0
tag = (entry.get("level3_tag") or "").strip()
if tag:
if tag in query:
score += 10.0
elif len(tag) > 1 and tag.lower() in q_lower:
score += 10.0
for kw in entry.get("search_keywords") or []:
k = (kw or "").strip()
if not k:
continue
if len(k) >= 2 and (k in query or k.lower() in q_lower):
score += 3.0
od = (entry.get("official_definition") or "").strip()
if od and len(od) > 2:
for chunk in od.replace(",", " ").replace("、", " ").replace(";", " ").split():
chunk = chunk.strip()
if len(chunk) > 2 and chunk in query:
score += 1.0
for ex in entry.get("common_examples") or []:
ex = (ex or "").strip()
if not ex:
continue
if ex in query or (len(ex) > 2 and ex.lower() in q_lower):
score += 5.0
pri = entry.get("priority") or "normal"
if pri == "high":
score *= 1.12
elif pri == "urgent":
score *= 1.2
return score
def search(self, query: str, top_k: int = 8) -> List[Tuple[dict, float]]:
if not query.strip() or not self._entries:
return []
scored: List[Tuple[dict, float]] = []
for entry in self._entries:
s = self._score_entry(query, entry)
scored.append((entry, s))
scored.sort(key=lambda x: x[1], reverse=True)
# 有分时优先非零;全零时仍返回若干条供弱参考(按 tag_id)
positive = [(e, s) for e, s in scored if s > 0]
if positive:
return positive[:top_k]
fallback = sorted(self._entries, key=lambda e: str(e.get("tag_id", "")))[:top_k]
return [(e, 0.0) for e in fallback]
def format_entries(self, hits: List[Tuple[dict, float]], include_score: bool = True) -> str:
lines: List[str] = []
for i, (entry, sc) in enumerate(hits, 1):
tid = entry.get("tag_id", "")
l3 = entry.get("level3_tag", "")
od = (entry.get("official_definition") or "").strip()
kws = "、".join(entry.get("search_keywords") or [])
exs = entry.get("common_examples") or []
ex_str = ";".join(exs[:3]) if exs else ""
ref = (entry.get("reference_link") or "").strip()
head = f"[{i}] tag_id={tid} 三级标签:{l3}"
if include_score:
head += f"(匹配度参考分:{sc:.2f})"
lines.append(head)
if od:
lines.append(f" 官方定义:{od}")
if kws:
lines.append(f" 关键词:{kws}")
if ex_str:
lines.append(f" 典型问法:{ex_str}")
if ref:
lines.append(f" 参考链接:{ref}")
return "\n".join(lines) if lines else "(知识库无条目或未匹配到相关内容)"
def build_context_for_dialog(self, dialog_data: str, top_k: int = 8) -> str:
hits = self.search(dialog_data, top_k=top_k)
if not hits:
return ""
return self.format_entries(hits, include_score=True)
# 进程内单例,批量标注与 Agent 共用
ecommerce_knowledge_base = ECommerceKnowledgeBase(RAG_ECOMMERCE_JSON)
# ==========================================
# 流程1:初始化环境
# ==========================================
cred_json_path = os.path.join(r"E:\TUOZHU\tuozhu1\GongDan\google-credential.json")
credentials = service_account.Credentials.from_service_account_file(
cred_json_path,
scopes=['https://www.googleapis.com/auth/cloud-platform']
)
client = genai.Client(
vertexai=True,
location="global",
project="gen-lang-client-0167357249",
credentials=credentials
)
print("✅ 流程1完成:Gemini客户端初始化成功")
# ==========================================
# 核心工具函数
# ==========================================
def determine_ams_model(row):
"""
根据sku_chinese_name和涉及AMS核心组件列判断AMS型号
优先级:AMS 2 Pro > AMS HT > AMS Lite > AMS
先检查sku_chinese_name,再检查涉及AMS核心组件
"""
# 定义型号关键词与对应型号的映射,按优先级排序
model_keywords = [
("AMS 2 Pro", "AMS 2 Pro"), # 第一优先级
("AMS HT", "AMS HT"), # 第二优先级
("AMS Lite", "AMS Lite"), # 第三优先级(标准写法)
("AMS lite", "AMS Lite"), # 第三优先级(小写lite兼容)
("AMS", "AMS") # 第四优先级
]
# 1. 先检查sku_chinese_name列(处理空值情况)
sku_name = str(row.get("sku_chinese_name", "")).lower()
for keyword, model in model_keywords:
if keyword.lower() in sku_name:
return model
# 2. 若sku_chinese_name无匹配,检查涉及AMS核心组件列
ams_component = str(row.get("涉及AMS核心组件", "")).lower()
for keyword, model in model_keywords:
if keyword.lower() in ams_component:
return model
# 3. 若均无匹配,返回空值
return ""
def init_genai_client() -> genai.Client:
"""初始化Google Gemini客户端"""
try:
credentials = service_account.Credentials.from_service_account_file(
CRED_JSON_PATH,
scopes=['https://www.googleapis.com/auth/cloud-platform']
)
return genai.Client(
vertexai=True,
location="global",
project=PROJECT_ID,
credentials=credentials
)
except Exception as e:
logging.critical(f"Gemini客户端初始化失败:{str(e)}")
raise
def detect_ticket_type(client: genai.Client, dialog_data: str, prompt_template: str) -> tuple:
"""调用LLM检测工单类型,返回类型和判断依据"""
try:
full_prompt = f"{prompt_template}\n\n【工单对话数据】:{dialog_data}"
response = client.models.generate_content(
model=MODEL_NAME,
config=types.GenerateContentConfig(
temperature=0.0, # 0保证结果稳定
top_p=0.95,
top_k=4
),
contents=full_prompt
)
if not response or not response.text:
raise ValueError("LLM返回空内容,未检测到工单类型")
# 解析JSON格式结果
response_json = json_repair.loads(response.text.strip())
ticket_type = response_json.get("type", "UNKNOWN").upper()
reason = response_json.get("reason", "").strip()
# 验证类型是否有效
if ticket_type not in ["AMS", "P2S", "E-COMMERCE", "FILAMENT", "STUDIO", "HANDY", "MAKERWORLD", "NONSENSE", "UNKNOWN"]:
ticket_type = "UNKNOWN"
return ticket_type, reason
except Exception as e:
logging.error(f"工单类型检测失败:{str(e)}")
return "UNKNOWN", "检测失败:" + str(e)[:50]
def call_classify_llm(
client: genai.Client,
dialog_data: str,
prompt_template: str,
rag_context: Optional[str] = None,
) -> Dict:
"""调用Gemini进行工单标注,返回解析后的JSON结果。rag_context 为可选知识库检索片段(如电商 e-com.json)。"""
try:
if rag_context and rag_context.strip():
full_prompt = (
f"{prompt_template}\n\n"
f"【知识库检索参考】(仅辅助对齐三级标签命名与业务含义,最终以工单原文与分类体系为准):\n{rag_context.strip()}\n\n"
f"【工单对话数据】:{dialog_data}"
)
else:
full_prompt = f"{prompt_template}\n\n【工单对话数据】:{dialog_data}"
response = client.models.generate_content(
model=MODEL_NAME,
config=types.GenerateContentConfig(
temperature=0.0, # 0保证标注结果稳定,无随机性
top_p=0.95,
top_k=4
),
contents=full_prompt
)
if not response or not response.text:
raise ValueError("LLM返回空内容,未生成工单标注结果")
return json_repair.loads(response.text.strip()) # 修复JSON格式错误
except Exception as e:
logging.error(f"LLM调用失败:{str(e)}")
raise
def extract_valid_llm_data(llm_output) -> Dict:
"""提取工单LLM返回结果中的有效数据,处理列表/字典格式异常"""
valid_data = {}
if isinstance(llm_output, list):
# 优先提取包含"核心信息"的字典(标注结果核心标识)
for item in llm_output:
if isinstance(item, dict) and "核心信息" in item:
valid_data = item
break
# 兜底:列表无有效字典时取最后一个元素
if not valid_data and len(llm_output) > 0:
last_item = llm_output[-1]
valid_data = last_item if isinstance(last_item, dict) else {}
elif isinstance(llm_output, dict):
valid_data = llm_output
else:
logging.warning(f"LLM返回无效数据类型:{type(llm_output)},内容:{str(llm_output)[:200]}")
return valid_data
def save_row_to_csv(result_dict: Dict, file_path: str):
"""线程安全地追加工单标注结果到CSV,中文防乱码"""
try:
df_single_row = pd.DataFrame([result_dict])
with file_save_lock:
file_exists = os.path.isfile(file_path)
df_single_row.to_csv(
file_path,
mode='a',
index=False,
header=not file_exists,
encoding='utf-8-sig'
)
except Exception as e:
logging.error(f"写入CSV缓存失败:{str(e)}")
def process_ticket_worker(client: genai.Client, row_tuple: tuple, type_detection_prompt: str, p2s_prompt: str, ams_prompt: str, ecommerce_prompt: str, filament_prompt: str, studio_prompt: str, handy_prompt: str, makerworld_prompt: str) -> Dict:
"""单个工单处理核心逻辑:检测类型+调用LLM+解析结果+填充字段+异常处理"""
idx, row = row_tuple
# 提取工单基础数据
dialog_data = str(row.get(DIALOG_COLUMN, "")).strip()
work_order_id = str(row.get(WORK_ORDER_ID_COLUMN, "未知工单号")).strip()
if not work_order_id or work_order_id.lower() == "nan":
work_order_id = "未知工单号"
log_prefix = f"[工单{idx + 1}][工单号:{work_order_id}]"
llm_result = None # 存储LLM原始结果,便于异常排查
# 初始化结果字典
result = {
"工单号": work_order_id,
"工单序号": idx + 1,
"工单内容": dialog_data,
"模型输出一级标签": "",
"模型输出二级标签": "",
"模型输出三级标签": "",
"模型输出四级标签": "",
"分类置信得分": 0.00,
"分类依据": "",
"核心故障现象": "",
"强关联关键信息": "",
"涉及核心功能/模块": "",
"工单场景": "",
"客服故障定位结论": "",
"建议标签": "",
"建议标签匹配依据": "",
"处理状态": "等待处理",
"工单类型": "",
"第一次分类依据": "",
"AMS型号": ""
}
try:
# 校验工单内容非空
if not dialog_data:
raise ValueError("工单对话数据为空")
# 1. 第一步:检测工单类型
ticket_type, type_reason = detect_ticket_type(client, dialog_data, type_detection_prompt)
result["工单类型"] = ticket_type
result["第一次分类依据"] = type_reason
logging.info(f"{log_prefix} 检测到工单类型:{ticket_type} | 依据:{type_reason[:100]}")
# 2. 处理无意义工单
if ticket_type == "NONSENSE":
# 直接标记为无意义工单,跳过第二次LLM调用
result["模型输出一级标签"] = "无意义工单"
result["模型输出二级标签"] = "无意义工单"
result["分类置信得分"] = 1.00
result["分类依据"] = "工单内容被识别为无意义,包含测试数据、占位符、广告或与3D打印机/AMS系统完全无关的内容"
result["核心故障现象"] = "无意义内容"
result["强关联关键信息"] = "无"
result["涉及核心功能/模块"] = "无"
result["工单场景"] = "无"
result["客服故障定位结论"] = "无"
result["建议标签"] = ""
result["建议标签匹配依据"] = ""
result["处理状态"] = "成功"
logging.info(f"{log_prefix} 处理成功 | 类型:{ticket_type} | 一级标签:无意义工单 | 二级标签:无意义工单 | 得分:1.00")
else:
# 3. 根据工单类型选择对应的标注提示词
if ticket_type == "AMS":
classify_prompt = ams_prompt
module_field = "涉及AMS核心组件"
elif ticket_type == "P2S":
classify_prompt = p2s_prompt
module_field = "涉及P2S核心功能/模块"
elif ticket_type == "E-COMMERCE":
classify_prompt = ecommerce_prompt
module_field = "涉及电商核心场景/模块"
elif ticket_type == "FILAMENT":
classify_prompt = filament_prompt
module_field = "涉及耗材信息"
elif ticket_type == "STUDIO":
classify_prompt = studio_prompt
module_field = "涉及Studio核心功能/模块"
elif ticket_type == "HANDY":
classify_prompt = handy_prompt
module_field = "涉及Handy相关场景/组件"
elif ticket_type == "MAKERWORLD":
classify_prompt = makerworld_prompt
module_field = "涉及MakerWorld核心功能/模块"
elif ticket_type == "UNKNOWN":
# UNKNOWN是一种类型,不是失败
result["模型输出一级标签"] = "用户提供信息无法判断"
result["模型输出二级标签"] = ""
result["分类置信得分"] = 0.00
result["分类依据"] = "无法确定工单类型,需要人工审核"
result["核心故障现象"] = "未知"
result["强关联关键信息"] = "无"
result["涉及核心功能/模块"] = "无"
result["工单场景"] = "无"
result["客服故障定位结论"] = "无"
result["建议标签"] = ""
result["建议标签匹配依据"] = ""
result["处理状态"] = "成功"
logging.info(
f"{log_prefix} 处理成功 | 类型:{ticket_type} | 一级标签:用户提供信息无法判断 | 得分:0.00")
# 跳过后续处理,但先写入CSV缓存
save_row_to_csv(result, CSV_TEMP_CACHE)
return result
else:
raise ValueError(f"无法确定工单类型:{ticket_type}")
# 4. 第二步:调用LLM进行标注(电商类工单注入 e-com.json 检索片段)
rag_extra = ""
if ticket_type == "E-COMMERCE":
rag_extra = ecommerce_knowledge_base.build_context_for_dialog(dialog_data, top_k=8)
llm_result = call_classify_llm(client, dialog_data, classify_prompt, rag_context=rag_extra or None)
# 5. 提取有效标注数据
valid_llm_data = extract_valid_llm_data(llm_result)
if not valid_llm_data:
raise ValueError("未提取到有效工单标注数据")
# 6. 填充核心信息字段
core_info = valid_llm_data.get("核心信息", {})
result["核心故障现象"] = core_info.get("核心故障现象", "").strip()
# 强关联关键信息:列表转字符串,便于Excel存储
result["强关联关键信息"] = ",".join(core_info.get("强关联关键信息", [])).strip()
result["涉及核心功能/模块"] = core_info.get(module_field, "").strip()
result["工单场景"] = core_info.get("工单场景", "").strip()
result["客服故障定位结论"] = core_info.get("客服故障定位结论", "").strip()
# 7. 对于AMS工单,判断型号
if ticket_type == "AMS":
# 构建包含必要信息的临时字典用于型号判断
temp_row = {
"sku_chinese_name": row.get("sku_chinese_name", ""),
"涉及AMS核心组件": core_info.get("涉及AMS核心组件", "")
}
ams_model = determine_ams_model(temp_row)
result["AMS型号"] = ams_model
# 7. 处理分类结果集(要求一级标签唯一,仅取第一个结果)
classify_results = valid_llm_data.get("分类结果集", [])
if not isinstance(classify_results, list) or len(classify_results) == 0:
raise ValueError("分类结果集格式错误或为空,无法提取标签")
label_data = classify_results[0]
# 8. 填充标签字段(严格按分类体系原文)
result["模型输出一级标签"] = label_data.get("一级标签", "用户提供信息无法判断").strip()
result["模型输出二级标签"] = label_data.get("二级标签", "").strip()
result["模型输出三级标签"] = label_data.get("三级标签", "").strip()
result["模型输出四级标签"] = label_data.get("四级标签", "").strip()
# 9. 填充置信得分(保留两位小数)
conf_score = label_data.get("置信得分", 0.00)
result["分类置信得分"] = round(float(conf_score), 2) if isinstance(conf_score, (int, float)) else 0.00
# 10. 填充分类依据等字段
result["分类依据"] = label_data.get("分类依据", "").strip()
result["建议标签"] = label_data.get("建议标签", "").strip()
result["建议标签匹配依据"] = label_data.get("建议标签匹配依据", "").strip()
# 兜底:一级标签为空时设为"用户提供信息无法判断"
if not result["模型输出一级标签"]:
result["模型输出一级标签"] = "用户提供信息无法判断"
result["分类置信得分"] = 0.00
# 更新处理状态
result["处理状态"] = "成功"
logging.info(f"{log_prefix} 处理成功 | 类型:{ticket_type} | 一级标签:{result['模型输出一级标签']} | 二级标签:{result['模型输出二级标签']} | 得分:{result['分类置信得分']}")
except Exception as e:
# 异常处理:截断错误信息,避免日志过长
error_msg = str(e)[:100]
result["处理状态"] = f"失败:{error_msg}"
logging.error(f"{log_prefix} 处理失败:{error_msg}")
# 异常时打印LLM原始结果,便于问题排查
if llm_result is not None:
logging.debug(f"{log_prefix} LLM原始返回:{str(llm_result)[:500]}")
# 仅成功处理的工单写入CSV临时缓存
if result["处理状态"] == "成功":
save_row_to_csv(result, CSV_TEMP_CACHE)
return result
# ==========================================
# 批量处理工单函数
# ==========================================
def batch_process_tickets():
"""工单批量标注主函数:统筹全流程"""
# 1. 清理旧缓存文件
if os.path.exists(CSV_TEMP_CACHE):
os.remove(CSV_TEMP_CACHE)
logging.info("已清理旧缓存文件")
# 2. 初始化LLM客户端和所有提示词
try:
client = init_genai_client()
# 加载工单类型检测提示词
with open(TICKET_TYPE_DETECTION_PROMPT, 'r', encoding='utf-8') as f:
type_detection_prompt = f.read().strip()
if not type_detection_prompt:
raise ValueError("工单类型检测提示词模板为空")
# 加载P2S标注提示词
with open(CLASSIFY_PROMPT_FILE_P2S, 'r', encoding='utf-8') as f:
p2s_prompt = f.read().strip()
if not p2s_prompt:
raise ValueError("P2S标注提示词模板为空")
# 加载AMS标注提示词
with open(CLASSIFY_PROMPT_FILE_AMS, 'r', encoding='utf-8') as f:
ams_prompt = f.read().strip()
if not ams_prompt:
raise ValueError("AMS标注提示词模板为空")
# 加载电商标注提示词
with open(CLASSIFY_PROMPT_FILE_ECOMMERCE, 'r', encoding='utf-8') as f:
ecommerce_prompt = f.read().strip()
if not ecommerce_prompt:
raise ValueError("电商标注提示词模板为空")
# 加载耗材标注提示词
with open(CLASSIFY_PROMPT_FILE_FILAMENT, 'r', encoding='utf-8') as f:
filament_prompt = f.read().strip()
if not filament_prompt:
raise ValueError("耗材标注提示词模板为空")
# 加载Studio标注提示词
with open(CLASSIFY_PROMPT_FILE_STUDIO, 'r', encoding='utf-8') as f:
studio_prompt = f.read().strip()
if not studio_prompt:
raise ValueError("Studio标注提示词模板为空")
# 加载Handy标注提示词
with open(CLASSIFY_PROMPT_FILE_HANDY, 'r', encoding='utf-8') as f:
handy_prompt = f.read().strip()
if not handy_prompt:
raise ValueError("Handy标注提示词模板为空")
# 加载MakerWorld标注提示词
with open(CLASSIFY_PROMPT_FILE_MAKERWORLD, 'r', encoding='utf-8') as f:
makerworld_prompt = f.read().strip()
if not makerworld_prompt:
raise ValueError("MakerWorld标注提示词模板为空")
except Exception as e:
logging.critical(f"初始化失败:{str(e)}")
raise
# 3. 读取工单数据并校验
try:
df_tickets = pd.read_csv(EXCEL_INPUT_PATH, encoding='utf-8-sig')
# 校验必要列存在
if DIALOG_COLUMN not in df_tickets.columns:
raise ValueError(f"CSV中未找到列:{DIALOG_COLUMN}")
if WORK_ORDER_ID_COLUMN not in df_tickets.columns:
raise ValueError(f"CSV中未找到列:{WORK_ORDER_ID_COLUMN}")
# 过滤空工单,重置索引
df_tickets = df_tickets.dropna(subset=[DIALOG_COLUMN]).reset_index(drop=True)
total_tickets = len(df_tickets)
if total_tickets == 0:
raise ValueError("输入CSV中无有效工单数据")
# 根据MAX_DATA_SIZE限制处理的数据量
if MAX_DATA_SIZE > 0 and total_tickets > MAX_DATA_SIZE:
df_tickets = df_tickets.head(MAX_DATA_SIZE).reset_index(drop=True)
logging.info(f"根据配置限制数据量,处理前{total_tickets}条,处理后{len(df_tickets)}条")
total_tickets = len(df_tickets)
# 统计空工单号数量
empty_wo_count = df_tickets[
df_tickets[WORK_ORDER_ID_COLUMN].isna() |
(df_tickets[WORK_ORDER_ID_COLUMN].astype(str).str.strip() == "") |
(df_tickets[WORK_ORDER_ID_COLUMN].astype(str).str.strip().str.lower() == "nan")
].shape[0]
if empty_wo_count > 0:
logging.warning(f"发现{empty_wo_count}条工单无工单号,将自动填充为「未知工单号」")
logging.info(f"成功读取{total_tickets}条工单数据,开始批量标注...")
except Exception as e:
logging.critical(f"读取工单数据失败:{str(e)}")
raise
# 4. 多线程批量处理工单
start_time = time.time()
all_results = []
with ThreadPoolExecutor(max_workers=MAX_WORKER_THREADS) as executor:
futures = [executor.submit(process_ticket_worker, client, (idx, row), type_detection_prompt, p2s_prompt, ams_prompt, ecommerce_prompt, filament_prompt, studio_prompt, handy_prompt, makerworld_prompt) for idx, row in df_tickets.iterrows()]
for future in as_completed(futures):
all_results.append(future.result())
# 等待所有线程完成并确保缓存文件写入完成
time.sleep(2) # 给文件系统一点时间完成写入
# 5. 重新处理失败的工单,最多尝试5次
max_retries = 5
retry_count = 0
failed_results = [result for result in all_results if not result["处理状态"].startswith("成功")]
while failed_results and retry_count < max_retries:
retry_count += 1
logging.info(f"第{retry_count}次重试:发现{len(failed_results)}条失败工单,开始重新处理...")
# 提取失败工单的原始数据
failed_indices = [result["工单序号"] - 1 for result in failed_results]
failed_rows = [(idx, df_tickets.iloc[idx]) for idx in failed_indices]
# 重新处理失败的工单
retry_results = []
with ThreadPoolExecutor(max_workers=MAX_WORKER_THREADS) as executor:
retry_futures = [executor.submit(process_ticket_worker, client, row_tuple, type_detection_prompt, p2s_prompt, ams_prompt, ecommerce_prompt, filament_prompt, studio_prompt, handy_prompt, makerworld_prompt) for row_tuple in failed_rows]
for future in as_completed(retry_futures):
retry_results.append(future.result())
# 等待重新处理完成
time.sleep(2)
# 更新失败的工单列表
failed_results = [result for result in retry_results if not result["处理状态"].startswith("成功")]
success_count = len(retry_results) - len(failed_results)
logging.info(f"第{retry_count}次重试完成,成功处理{success_count}条,剩余失败{len(failed_results)}条")
if failed_results:
logging.warning(f"达到最大重试次数({max_retries}次),仍有{len(failed_results)}条工单处理失败")
# 6. 生成最终Excel标注结果
try:
if os.path.exists(CSV_TEMP_CACHE):
# 读取缓存数据,按工单序号排序
final_df = pd.read_csv(CSV_TEMP_CACHE, encoding='utf-8-sig')
final_df = final_df.sort_values("工单序号").reset_index(drop=True)
# 保存到Excel,使用更高效的引擎
final_df.to_excel(EXCEL_OUTPUT_PATH, index=False)
# 统计处理结果
total_success = len(final_df[final_df["处理状态"] == "成功"])
total_failed = len(all_results) - total_success
# 打印处理结果
logging.info(f"\n===== 工单标注任务完成 =====")
logging.info(f"总处理工单数:{len(all_results)}")
logging.info(f"成功:{total_success} 条")
logging.info(f"失败:{total_failed} 条")
logging.info(f"成功率:{total_success / len(all_results) * 100:.2f}%")
logging.info(f"输出文件:{EXCEL_OUTPUT_PATH}")
logging.info(f"临时缓存:{CSV_TEMP_CACHE}")
return {
"total": len(all_results),
"success": total_success,
"failed": total_failed,
"success_rate": f"{total_success / len(all_results) * 100:.2f}%",
"output_file": EXCEL_OUTPUT_PATH
}
else:
logging.error("未生成缓存文件,无法生成最终结果")
return {"error": "未生成缓存文件"}
except Exception as e:
logging.error(f"生成最终结果失败:{str(e)}")
return {"error": str(e)}
# ==========================================
# 模拟工单数据库
# ==========================================
class WorkOrderDatabase:
def __init__(self):
self.data = {
"GD202506001": "工单GD202506001:状态是【处理中】,处理人是张三,预计明天完成",
"GD202506002": "工单GD202506002:状态是【已完成】,处理人是李四,昨天已结案"
}
def query(self, gongdan_id: str) -> str:
return self.data.get(gongdan_id, "没找到这个工单")
# 初始化工单数据库
db = WorkOrderDatabase()
# ==========================================
# 定义工具
# ==========================================
tools = types.Tool(
function_declarations=[
types.FunctionDeclaration(
name="query_work_order",
description="用户问工单进度、状态时,用这个工具查",
parameters=types.Schema(
type=types.Type.OBJECT,
properties={
"gongdan_id": types.Schema(
type=types.Type.STRING,
description="要查的工单编号,比如GD202506001"
)
},
required=["gongdan_id"]
)
),
types.FunctionDeclaration(
name="process_tickets",
description="批量处理工单,进行类型检测和标签标注",
parameters=types.Schema(
type=types.Type.OBJECT,
properties={
"max_data_size": types.Schema(
type=types.Type.INTEGER,
description="处理的数据量,-1表示全部,正数表示指定数量"
)
},
required=["max_data_size"]
)
),
types.FunctionDeclaration(
name="query_ecommerce_knowledge",
description="根据用户问题或工单摘要,检索电商业务知识库(三级标签定义、关键词、典型问法),用于解答商城/订单/物流/支付等电商相关问题或辅助理解标签含义",
parameters=types.Schema(
type=types.Type.OBJECT,
properties={
"query": types.Schema(
type=types.Type.STRING,
description="检索查询文本,如用户原话、工单对话摘要、关键词"
),
"top_k": types.Schema(
type=types.Type.INTEGER,
description="返回最相关的条目数量,默认8,最大建议20"
)
},
required=["query"]
)
)
]
)
print("✅ 流程2完成:工具注册成功")
# ==========================================
# 创建Agent类来管理工具调用
# ==========================================
class WorkOrderAgent:
def __init__(self, client, tools, db, kb=None):
self.client = client
self.tools = tools
self.db = db
self.kb = kb if kb is not None else ecommerce_knowledge_base
def run(self, user_question):
# 第一步:发送问题给模型
response = self.client.models.generate_content(
model="gemini-3-flash-preview",
contents=user_question,
config={"tools": [self.tools]}
)
# 第二步:检查是否需要调用工具
candidate = response.candidates[0]
if hasattr(candidate, 'content') and candidate.content:
parts = candidate.content.parts
# 检查是否有function_call部分
function_call_part = None
for part in parts:
if hasattr(part, 'function_call') and part.function_call:
function_call_part = part.function_call
break
if function_call_part:
print(f"🤖 模型决定调用【{function_call_part.name}】工具")
# 解析模型要的参数
if hasattr(function_call_part, 'name') and hasattr(function_call_part, 'args'):
if function_call_part.name == "query_work_order" and "gongdan_id" in function_call_part.args:
target_gongdan_id = function_call_part.args["gongdan_id"]
print(f" 模型要查的工单编号:{target_gongdan_id}")
# 执行工具(查数据库)
gongdan_result = self.db.query(target_gongdan_id)
print(f"🔍 执行工具结果:{gongdan_result}")
# 回传给模型
final_response = self.client.models.generate_content(
model="gemini-3-flash-preview",
contents=[
user_question,
types.Part(
function_response=types.FunctionResponse(
name="query_work_order",
response={"result": gongdan_result}
)
)
]
)
print(f"✅ 流程完成:模型生成最终答案")
print("\n📝 最终答案:")
if hasattr(final_response, 'text'):
return final_response.text
else:
return "模型未返回文本响应"
elif function_call_part.name == "process_tickets" and "max_data_size" in function_call_part.args:
max_data_size = function_call_part.args["max_data_size"]
print(f" 模型要处理的数据量:{max_data_size}")
# 执行工单处理
global MAX_DATA_SIZE
MAX_DATA_SIZE = max_data_size
process_result = batch_process_tickets()
print(f"🔍 执行工具结果:{process_result}")
# 回传给模型
final_response = self.client.models.generate_content(
model="gemini-3-flash-preview",
contents=[
user_question,
types.Part(
function_response=types.FunctionResponse(
name="process_tickets",
response={"result": process_result}
)
)
]
)
print(f"✅ 流程完成:模型生成最终答案")
print("\n📝 最终答案:")
if hasattr(final_response, 'text'):
return final_response.text
else:
return "模型未返回文本响应"
elif function_call_part.name == "query_ecommerce_knowledge" and "query" in function_call_part.args:
q = str(function_call_part.args.get("query", "")).strip()
top_k = function_call_part.args.get("top_k", 8)
try:
top_k = int(top_k)
except (TypeError, ValueError):
top_k = 8
top_k = max(1, min(top_k, 20))
print(f" 电商知识库检索 query={q[:80]}... top_k={top_k}")
hits = self.kb.search(q, top_k=top_k)
kb_text = self.kb.format_entries(hits, include_score=True)
print(f"🔍 执行工具结果长度:{len(kb_text)} 字符")
final_response = self.client.models.generate_content(
model="gemini-3-flash-preview",
contents=[
user_question,
types.Part(
function_response=types.FunctionResponse(
name="query_ecommerce_knowledge",
response={"result": kb_text}
)
)
]
)
print(f"✅ 流程完成:模型生成最终答案")
print("\n📝 最终答案:")
if hasattr(final_response, 'text'):
return final_response.text
else:
return "模型未返回文本响应"
else:
return "❌ 函数调用参数不正确"
else:
return "❌ 函数调用格式不正确"
else:
# 如果模型觉得不用查工具,直接回答
print("🤖 模型觉得不用查工具,直接回答:")
if hasattr(response, 'text'):
return response.text
else:
return "模型未返回文本响应"
else:
# 如果模型没有返回内容
print("❌ 模型未返回内容")
if hasattr(response, 'text'):
return f"模型文本响应:{response.text}"
else:
return "模型无文本响应"
# 初始化Agent(注入电商 RAG 知识库)
agent = WorkOrderAgent(client, tools, db, kb=ecommerce_knowledge_base)
print("✅ 流程3完成:Agent初始化成功")
# ==========================================
# 执行Agent
# ==========================================
user_question = "帮我处理工单,使用全部数据"
print(f"\n🗣️ 用户提问:{user_question}")
# 执行Agent
result = agent.run(user_question)
print(result)
rag评分
这个 _score_entry 函数是一个基于“关键词/字符串重叠度”的纯规则打分算法。它的核心逻辑很简单:用户的问题和知识库条目,文字重叠得越多,分数就越高。
下面我把它拆解成 5 个打分维度,并用一个完整的例子带你算一遍。
一、打分维度详解(按执行顺序)
我们先约定一组模拟数据,用于下面所有的举例计算:
- 用户输入 (Query):
"我的打印机坏了,怎么申请售后退货退款?" - 知识库条目 (Entry):
{ "level3_tag": "订单退货退款", "search_keywords": ["退货", "退款", "售后", "申请退货"], "official_definition": "用户针对已购买商品申请退货退款或售后服务", "common_examples": ["我要退货退款", "怎么申请售后"], "priority": "high" }

1. 三级标签匹配 (权重最高:+10.0分)
这是最重要的匹配项。
- 逻辑:如果三级标签的完整字符串出现在用户问题中,直接加10分。
- 注意:它做了大小写不敏感处理(先全转小写再比一次)。
📝 套用我们的例子:
- 标签是
"订单退货退款"。 - 用户问题里有
"退货退款",但没有完整的"订单退货退款"。 - 但是,代码有个
elif逻辑:如果标签小写后在 query 小写里,也加分。 - 等等,让我们再仔细看代码:
- 代码第一检查:
tag in query? (“订单退货退款” 在 “我的打印机坏了…” 里吗?不在)。 - 代码第二检查:
tag.lower() in q_lower?tag.lower()是"订单退货退款"。q_lower是"我的打印机坏了,怎么申请售后退货退款?"。- 虽然不全包含,但如果标签是
"退货退款",那就匹配了。
- 代码第一检查:
- 为了演示方便,我们假设用户问题里包含了完整标签,或者我们调整一下标签。假设这一项匹配成功。
- 得分:+10.0
2. 关键词匹配 (权重次高:每个 +3.0分)
- 逻辑:遍历
search_keywords列表。只要关键词长度≥2,且出现在用户问题里,每个词加3分。 - 特点:积少成多,这是最容易得分的项。
📝 套用我们的例子:
关键词列表是 ["退货", "退款", "售后", "申请退货"]。
"退货":在问题里 -> +3.0"退款":在问题里 -> +3.0"售后":在问题里 -> +3.0"申请退货":在问题里 -> +3.0
- 得分:3.0 × 4 = +12.0
- 累计总分:10.0 + 12.0 = 22.0
3. 官方定义分词匹配 (权重最低:每个词 +1.0分)
- 逻辑:把“官方定义”一段话,按标点符号(,、;)和空格拆成单个的词。只要词长度>2,且在用户问题里,每个词加1分。
- 目的:作为关键词的补充,捞一些漏网之鱼。
📝 套用我们的例子:
定义是 "用户针对已购买商品申请退货退款或售后服务"。
- 拆词:
["用户", "针对", "已购买", "商品", "申请", "退货退款", "售后服务"...] - 匹配:
"申请"(长度=2,不满足>2,跳过)"退货退款"(在问题里,长度>2) -> +1.0"售后服务"(不在问题里,问题只有"售后")
- 得分:+1.0
- 累计总分:22.0 + 1.0 = 23.0
4. 典型问法匹配 (权重中等:每条 +5.0分)
- 逻辑:看
common_examples里的某一整句话,是否出现在用户问题里。如果是,每条加5分。 - 特点:这是“句子级”的匹配,比单个关键词更精准。
📝 套用我们的例子:
例句列表是 ["我要退货退款", "怎么申请售后"]。
"我要退货退款":用户说的是"怎么申请…“,不是"我要…”,不匹配。"怎么申请售后":用户说的是"怎么申请售后退货退款",包含了这句话!
- 得分:+5.0
- 累计总分:23.0 + 5.0 = 28.0
5. 优先级加成 (最后一步:乘法)
- 逻辑:在上面算完的总分基础上,乘以一个系数。
high(高优) × 1.12urgent(紧急) × 1.2normal(普通) × 1.0 (不加分)
📝 套用我们的例子:
- 条目优先级是
"high"。 - 最终得分:28.0 × 1.12 = 31.36
二、完整的“算分”过程演示
假设现在有两个知识库条目,我们来看看代码是怎么选出来的。
用户问题 (Query): "怎么申请退款"
| 步骤 | 条目 A: “订单退款” (priority: high) | 得分 | 条目 B: “物流查询” (priority: normal) | 得分 |
|---|---|---|---|---|
| 1. 标签 | “订单退款” 不在 query 里 | 0 | “物流查询” 不在 query 里 | 0 |
| 2. 关键词 | 匹配到 “退款”、“申请” (假设有关键词) | +6.0 | 匹配到 “查询” | +3.0 |
| 3. 定义 | 匹配到 “退款” | +1.0 | 无匹配 | 0 |
| 4. 例句 | 匹配到 “怎么申请退款” | +5.0 | 无匹配 | 0 |
| 小计 | 12.0 | 3.0 | ||
| 5. 加成 | × 1.12 | 13.44 | × 1.0 | 3.0 |
结果: 条目 A (13.44分) 排在条目 B (3.0分) 前面。

三、这个算法的特点
- 纯规则,无 AI:它不理解语义,只认字符串。比如它不知道“退款”和“退钱”是一个意思。
- 权重设计合理:
- 标签(10分)和例句(5分)代表精准匹配。
- 关键词(3分)代表模糊匹配。
- 定义分词(1分)代表补充兜底。
- 业务优先级:最后通过乘法系数,保证业务上认为重要的条目(如退款)能排在更前面。
完整的流程:
- LLM 看第一遍:判断是电商还是硬件问题。
- Python 规则算分:如果是电商,去 JSON 里找最相关的标签定义。
- LLM 看第二遍:看着 Python 找出来的“参考答案”,进行最终的标准化标注。
更多推荐




所有评论(0)