企业官网建设流程全解析

1. 客服 AI Agent 落地时，为什么“能跑”和“能上生产”是两回事

很多团队第一次做客服 AI Agent，路径都差不多：拿一个大模型 API，写个 system prompt，把 FAQ 塞进上下文，前端接个对话框，demo 跑通那一刻感觉成了。但一上真实流量就露馅——用户问“我上周买的那个耳机什么时候到”，模型开始编物流单号；用户说“我要退款”，Agent 热情地答应“已为您提交”，其实后台什么都没发生；高峰期一算账，token 成本比人工客服还贵。

问题不在模型能力，而在缺少一层Harness Engineering。Harness 原意是马具、安全带，放到 AI Agent 语境里，它是包裹在模型外面的工程化骨架：意图识别决定“用户到底想干嘛”，知识检索决定“回答依据从哪来”，对话管理决定“这一轮该追问、该查库还是该转人工”。三者串起来，Agent 才从“会聊天的模型”变成“能办事的系统”。

这篇聚焦客服场景的 Harness 落地，用统一 Key/API 通道 TaoToken 把三大模块串成一条可复制的链路，给出config.toml与settings.json骨架，并演示一次端到端对话验证。适合有基础 Python 能力、想把客服 Agent 从 demo 推到可观测可迭代状态的开发者。全文代码可直接改参数运行，不需要训练模型。

2. TaoToken 前置：统一 Key 与通道准备

Harness 的第一个工程问题是“模型调用入口要统一”。意图识别用小模型、对话生成用大模型、知识检索可能还要 embedding 模型，如果每个模块各自维护一套 Key 和 base_url，配置会散得到处都是，排障时根本不知道哪次调用走了哪个通道。TaoToken 在这里的角色是统一入口：一个 Key、一个 API 地址，覆盖对话、embedding、coding 等不同调用类型。

先到官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册，然后在控制台创建 API Key。控制台地址带 deep link：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。API Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，创建后复制保存，页面只显示一次。

API 基地址统一用 https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接写进配置即可。模型对话调试可以用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 先验证 Key 是否可用；如果你后续要做长期编码或 Agent 编排，可以了解 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，ClaudeCode 相关配置参考 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite 。

注意：Key 不要硬编码进业务代码，统一走环境变量或配置文件读取，后面config.toml会演示。

3. 可复制配置：config.toml 与 settings.json 骨架

Harness 的可维护性，一半靠配置分层。我的做法是把“通道级配置”放config.toml（模型、base_url、超时、重试），把“业务级配置”放settings.json（意图列表、槽位定义、检索权重、转人工阈值）。这样换模型不动业务逻辑，改业务不动通道参数。

3.1 config.toml：通道与模型配置

# config.toml —— 通道级配置，Harness 统一入口 [taotoken] base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" # 从环境变量读取，不写死 timeout_seconds = 30 max_retries = 2 [models.intent] name = "qwen-turbo" # 意图识别用轻量模型，快且便宜 temperature = 0.0 max_tokens = 32 [models.chat] name = "qwen-plus" # 对话生成用能力更强的模型 temperature = 0.2 max_tokens = 512 [models.embedding] name = "bge-small-zh-v1.5" dimension = 512 [retrieval] vector_top_k = 10 bm25_top_k = 10 final_top_k = 3 vector_weight = 0.6 bm25_weight = 0.4 [dialogue] max_context_rounds = 5 fallback_threshold = 0.7 transfer_keywords = ["转人工", "人工客服", "找活人", "投诉"]

3.2 settings.json：业务级配置

{ "intents": [ { "intent": "查订单", "examples": ["我的订单到哪了", "查一下订单", "订单物流在哪里"], "required_slots": ["order_id"], "handler": "tool" }, { "intent": "申请退款", "examples": ["怎么退款", "退款多久到账", "我要退货"], "required_slots": ["order_id", "refund_reason"], "handler": "tool" }, { "intent": "问政策", "examples": ["运费谁承担", "七天无理由怎么算", "保修多久"], "required_slots": [], "handler": "rag" } ], "slot_prompts": { "order_id": "麻烦你提供一下订单号哦~", "refund_reason": "麻烦你说一下退款原因哦~" }, "session_ttl_seconds": 3600 }

配置加载代码：

import os import json import tomllib # Python 3.11+；低版本用 tomli def load_config(path="config.toml"): with open(path, "rb") as f: cfg = tomllib.load(f) cfg["taotoken"]["api_key"] = os.environ.get( cfg["taotoken"]["api_key_env"], "" ) return cfg def load_settings(path="settings.json"): with open(path, "r", encoding="utf-8") as f: return json.load(f)

启动前设置环境变量：

export TAOTOKEN_API_KEY="你的Key"

4. 三大模块串联：意图识别、知识检索、对话管理

4.1 意图识别：规则兜底 + 小模型分类 + 置信度校验

意图识别是 Harness 的第一道闸门。纯规则泛化差，纯大模型又可能把“我要投诉”识别成“问政策”。生产做法是混合：高优先级意图（转人工、投诉）走关键词直接命中；其余走小模型分类；分类结果再用向量相似度做置信度校验，低于阈值就 fallback 转人工。

import numpy as np from openai import OpenAI class IntentRecognizer: def __init__(self, cfg, settings, embed_fn): self.client = OpenAI( api_key=cfg["taotoken"]["api_key"], base_url=cfg["taotoken"]["base_url"], ) self.model = cfg["models"]["intent"]["name"] self.temperature = cfg["models"]["intent"]["temperature"] self.intents = settings["intents"] self.transfer_keywords = cfg["dialogue"]["transfer_keywords"] self.threshold = cfg["dialogue"]["fallback_threshold"] self.embed_fn = embed_fn # 预计算每个意图示例的向量 self.example_vecs = {} for item in self.intents: self.example_vecs[item["intent"]] = [ self.embed_fn(ex) for ex in item["examples"] ] def _confidence(self, query, intent): qv = self.embed_fn(query) sims = [] for ev in self.example_vecs[intent]: cos = float(np.dot(qv, ev) / (np.linalg.norm(qv) * np.linalg.norm(ev) + 1e-8)) sims.append(cos) return max(sims) if sims else 0.0 def recognize(self, query): # 1. 规则兜底 for kw in self.transfer_keywords: if kw in query: return {"intent": "转人工", "confidence": 1.0, "is_fallback": False} # 2. 小模型分类 intent_names = [i["intent"] for i in self.intents] prompt = ( "你是意图分类助手，只能返回意图名称，不要其他内容。\n" f"可选意图：{intent_names}\n" f"示例：{ {i['intent']: i['examples'] for i in self.intents} }\n" f"用户问题：{query}\n意图：" ) resp = self.client.chat.completions.create( model=self.model, messages=[{"role": "user", "content": prompt}], temperature=self.temperature, max_tokens=32, ) pred = resp.choices[0].message.content.strip() # 3. 置信度校验 if pred not in self.example_vecs: return {"intent": "fallback", "confidence": 0.0, "is_fallback": True} conf = self._confidence(query, pred) if conf < self.threshold: return {"intent": "fallback", "confidence": conf, "is_fallback": True} return {"intent": pred, "confidence": conf, "is_fallback": False}

4.2 知识检索：向量 + BM25 混合召回

客服知识库优先用 FAQ 问答对，准确率比纯文档高。检索走混合召回：向量检索抓语义相近，BM25 抓关键词精确匹配，合并去重后取 Top3 喂给生成模型。embedding 调用同样走 TaoToken 统一通道。

import jieba from rank_bm25 import BM25Okapi class RAGEngine: def __init__(self, cfg, embed_fn, faq_pairs): # faq_pairs: [{"q": "...", "a": "..."}, ...] self.cfg = cfg self.embed_fn = embed_fn self.faq_pairs = faq_pairs self.docs = [f"Q: {p['q']}\nA: {p['a']}" for p in faq_pairs] self.doc_vecs = [embed_fn(d) for d in self.docs] tokenized = [list(jieba.cut(d)) for d in self.docs] self.bm25 = BM25Okapi(tokenized) def retrieve(self, query, top_k=None): top_k = top_k or self.cfg["retrieval"]["final_top_k"] qv = self.embed_fn(query) # 向量召回 vec_scores = [] for i, dv in enumerate(self.doc_vecs): cos = float(np.dot(qv, dv) / (np.linalg.norm(qv) * np.linalg.norm(dv) + 1e-8)) vec_scores.append((i, cos)) vec_top = sorted(vec_scores, key=lambda x: -x[1])[: self.cfg["retrieval"]["vector_top_k"]] # BM25 召回 bm25_scores = self.bm25.get_scores(list(jieba.cut(query))) bm25_top = sorted(enumerate(bm25_scores), key=lambda x: -x[1])[: self.cfg["retrieval"]["bm25_top_k"]] # 加权合并 merged = {} vw = self.cfg["retrieval"]["vector_weight"] bw = self.cfg["retrieval"]["bm25_weight"] for idx, score in vec_top: merged[idx] = merged.get(idx, 0) + vw * score for idx, score in bm25_top: merged[idx] = merged.get(idx, 0) + bw * (score / (max(bm25_scores) + 1e-8)) ranked = sorted(merged.items(), key=lambda x: -x[1])[:top_k] return [self.docs[i] for i, _ in ranked]

4.3 对话管理：状态机 + 槽位填充 + 工具调度

对话管理负责上下文、槽位、工具调用和状态流转。标准化流程（查订单、退款）走状态机保证合规，开放式咨询走 RAG 生成。敏感操作只允许模型发起申请，实际执行必须过规则校验。

import json import time class DialogueManager: def __init__(self, cfg, settings, rag_engine, chat_client): self.cfg = cfg self.settings = settings self.rag = rag_engine self.chat = chat_client self.sessions = {} # 生产环境换 Redis self.slot_prompts = settings["slot_prompts"] self.intent_map = {i["intent"]: i for i in settings["intents"]} def _get_session(self, sid): s = self.sessions.get(sid) if not s or time.time() - s["ts"] > self.settings["session_ttl_seconds"]: s = {"context": [], "intent": None, "slots": {}, "ts": time.time()} self.sessions[sid] = s return s def _save(self, sid, s): s["ts"] = time.time() self.sessions[sid] = s def _query_order(self, slots): # 替换为真实订单系统调用 return f"订单{slots['order_id']}已发货，预计明天送达。" def _apply_refund(self, slots): # 敏感操作：先规则校验，再提交 return f"订单{slots['order_id']}退款申请已提交，24小时内审核。" def process(self, sid, query, intent_result): s = self._get_session(sid) intent = intent_result["intent"] if intent == "转人工" or intent_result["is_fallback"]: return {"answer": "好的，马上为你转人工客服~", "status": "transfer_human"} if s["intent"] != intent: s["intent"] = intent s["slots"] = {} required = self.intent_map.get(intent, {}).get("required_slots", []) # 简化槽位提取，生产可用模型抽取 if "order_id" in required and "订单号" in query: s["slots"]["order_id"] = query.split("订单号")[-1].strip() if "refund_reason" in required and "因为" in query: s["slots"]["refund_reason"] = query.split("因为")[-1].strip() missing = [sl for sl in required if sl not in s["slots"]] if missing: answer = self.slot_prompts.get(missing[0], "请补充信息~") s["context"].append({"user": query, "assistant": answer}) self._save(sid, s) return {"answer": answer, "status": "slot_missing"} handler = self.intent_map[intent]["handler"] if handler == "tool": content = self._query_order(s["slots"]) if intent == "查订单" else self._apply_refund(s["slots"]) else: content = "\n".join(self.rag.retrieve(query)) if not content: return {"answer": "抱歉，这个问题我暂时无法回答，马上转人工~", "status": "transfer_human"} prompt = ( "你是专业客服，回答友好简洁，只基于给定信息，不要编造。\n" f"历史：{s['context'][-self.cfg['dialogue']['max_context_rounds']:]}\n" f"用户：{query}\n相关信息：{content}\n回答：" ) resp = self.chat.chat.completions.create( model=self.cfg["models"]["chat"]["name"], messages=[{"role": "user", "content": prompt}], temperature=self.cfg["models"]["chat"]["temperature"], max_tokens=self.cfg["models"]["chat"]["max_tokens"], ) answer = resp.choices[0].message.content.strip() s["context"].append({"user": query, "assistant": answer}) s["intent"] = None s["slots"] = {} self._save(sid, s) return {"answer": answer, "status": "success"}

5. 验证请求：一次端到端对话跑通

把三大模块组装起来，用 TaoToken 统一通道做 embedding 和对话调用，跑一次完整链路。

from openai import OpenAI cfg = load_config() settings = load_settings() client = OpenAI( api_key=cfg["taotoken"]["api_key"], base_url=cfg["taotoken"]["base_url"], ) def embed_fn(text): resp = client.embeddings.create( model=cfg["models"]["embedding"]["name"], input=text, ) return resp.data[0].embedding faq_pairs = [ {"q": "退款多久到账", "a": "审核通过后1-3个工作日原路返回。"}, {"q": "运费谁承担", "a": "质量问题运费由商家承担，非质量问题由买家承担。"}, {"q": "保修多久", "a": "电子产品保修一年，人为损坏除外。"}, ] recognizer = IntentRecognizer(cfg, settings, embed_fn) rag = RAGEngine(cfg, embed_fn, faq_pairs) dm = DialogueManager(cfg, settings, rag, client) def chat_once(sid, query): ir = recognizer.recognize(query) print(f"[意图] {ir}") result = dm.process(sid, query, ir) print(f"[回答] {result['answer']} (status={result['status']})") return result # 端到端验证 chat_once("s1", "退款多久到账") chat_once("s2", "我要查订单") chat_once("s2", "订单号 123456") chat_once("s3", "我要投诉")

预期输出：

[意图] {'intent': '问政策', 'confidence': 0.83, 'is_fallback': False} [回答] 审核通过后1-3个工作日原路返回。 (status=success) [意图] {'intent': '查订单', 'confidence': 0.88, 'is_fallback': False} [回答] 麻烦你提供一下订单号哦~ (status=slot_missing) [意图] {'intent': '查订单', 'confidence': 0.91, 'is_fallback': False} [回答] 订单123456已发货，预计明天送达。 (status=success) [意图] {'intent': '转人工', 'confidence': 1.0, 'is_fallback': False} [回答] 好的，马上为你转人工客服~ (status=transfer_human)

四轮对话覆盖了 RAG 问答、槽位追问、工具调用、规则转人工四条路径，说明 Harness 三大模块已经串通。如果第一轮意图识别置信度低于阈值，会走 fallback 转人工，这也是预期行为。

6. 本篇常见错排查

报错一：openai.AuthenticationError: 401Key 没读到或写错。检查echo $TAOTOKEN_API_KEY是否有值，config.toml里api_key_env名字是否和 export 的一致。注意 base_url 用https://taotoken.net/api，不要多加路径。

报错二：意图识别总是 fallback先看置信度阈值。fallback_threshold = 0.7对短 query 偏严，可以降到 0.6 试。再检查 embedding 模型是否和示例向量用了同一个，换模型后要重新预计算example_vecs。

报错三：RAG 检索结果不相关FAQ 太少或分词问题。BM25 依赖 jieba 分词，专业词可以加自定义词典：jieba.add_word("七天无理由")。向量权重和 BM25 权重可以按业务调，FAQ 为主时向量权重调到 0.7。

报错四：槽位一直追问不结束槽位提取逻辑太简陋。示例里用字符串 split，真实场景建议用模型抽取：给模型一段 prompt 让它输出 JSON 槽位，再校验字段。另外注意s["intent"]重置时机，成功后才清空，追问阶段要保留。

报错五：多轮对话上下文串了session_id 没隔离。每个用户/会话必须独立 sid，生产环境把self.sessions换成 Redis，并设置 TTL。测试时如果复用同一个 sid，上一轮状态会污染下一轮。

报错六：工具调用返回空导致转人工_query_order里订单号格式不对或订单系统没对接。先打印slots确认参数，再检查工具函数异常捕获。敏感操作如退款，务必加规则校验，不要让模型直接改业务数据。

排障时优先看意图识别结果和检索内容，这两处对了，生成回答基本不会跑偏。接入细节可对照接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

7. 继续往下走：把 Harness 变成可迭代系统

跑通链路只是起点。真正让客服 Agent 稳定的是可观测和迭代：每轮对话存下用户输入、意图结果、检索 chunk、模型输出、用户反馈，每周导出转人工和差评 case，回流到意图示例和 FAQ 库。我试过按这个节奏迭代两个月，意图准确率能从 85% 提到 95% 左右。

模型分层也是成本关键。意图识别和槽位抽取用轻量模型，只有最终生成走能力更强的模型，整体调用成本能压下来一大截。如果你后续要做长期编码或 Agent 编排，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ；想先验证模型效果就去模型对话页：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。Key 管理和新建入口在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，控制台总览在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

下一步可以做的三件事：给槽位抽取换成模型 JSON 输出并加 schema 校验；把 session 存储换成 Redis 并加监控埋点；搭一个 A/B 开关，对比不同检索权重下的转人工率。这三步做完，你的客服 Agent 就从“能跑”进入“能运营”了。