项目简介：利用多智能体 Multi‑Agent 分工，拆分用户画像 Agent、商品召回 Agent、排序 Agent、策略 Agent、对话 Agent，实现智能化电商商品推荐；基于 Python+LangChain + 向量数据库，全套可复现代码、架构示意图说明、分步教程。
编程语言：Python3.9‑3.11；框架：LangChain、LangGraph、FAISS、OpenAI‑API / 本地大模型、Pandas

一、整体架构原理（多 Agent 分工）

1.1 五大独立智能体职责

1.2 系统数据流

用户输入 → 对话 Agent → 用户画像 Agent → 商品召回 Agent → 排序 Agent → 策略过滤 → 返回推荐结果

LangGraph 负责多个 Agent 之间调度、状态传递、循环纠错。

1.3 架构文字版示意图（可自行绘图）

用户请求 ↓ 【对话交互Agent】 ↓ 【用户画像Agent】→ 用户标签：{价格区间、品类、风格、偏好品牌} ↓ 【商品召回Agent】→ 向量数据库召回Top‑20候选商品 ↓ 【精排打分Agent】→ 综合权重打分 ↓ 【策略风控Agent】→ 过滤违规商品、活动加权 ↓ 返回Top‑N推荐结果+推荐解释

二、环境依赖安装

2.1 安装第三方库

pipinstalllangchain langgraph langchain-openai faiss-cpu pandas numpy sentence-transformers python-dotenv

• langgraph：多 Agent 工作流调度

• sentence‑transformers：商品文本向量化

• faiss‑cpu：轻量级本地向量数据库，用于商品相似度召回

2.2 项目目录结构

ecommerce_multi_agent/ ├── .env # 大模型密钥配置 ├── main.py # 主程序入口、Agent调度 ├── user_agent.py # 用户画像智能体 ├── recall_agent.py # 商品召回智能体 ├── rank_agent.py # 排序打分智能体 ├── policy_agent.py # 策略过滤智能体 ├── chat_agent.py # 入口对话Agent ├── goods_data.csv # 模拟电商商品数据集 └── vector_db/ # FAISS向量库持久化文件夹

三、配置 .env 文件

OPENAI_API_KEY=sk-xxx OPENAI_BASE_URL=https://api.openai.com/v1 LLM_MODEL=gpt-3.5-turbo

无海外接口可替换为通义千问、DeepSeek、Ollama 本地大模型。

四、数据集准备 goods_data.csv

复制下面模拟电商商品数据，保存为 csv

goods_id,name,category,price,score,sales,tag 1,夏季冰丝短袖,男装,79.9,4.8,2300,冰丝 透气 薄款 2,纯棉宽松T恤,男装,59.9,4.7,3600,纯棉 休闲 百搭 3,高腰牛仔短裤,女装,89.9,4.6,1800,牛仔 显瘦 夏季 4,防晒连衣裙,女装,129.9,4.9,2900,碎花 防晒 长裙 5,运动跑鞋,鞋靴,199,4.8,5200,减震 透气 跑步 6,通勤帆布包,配饰,39.9,4.5,4100,大容量 学生 通勤 7,男士皮带,配饰,69.9,4.3,1200,商务 自动扣 8,冰丝阔腿裤,女装,75,4.7,2600,垂感 高腰 夏天

五、各个 Agent 完整代码实现

5.1 加载公共配置与工具 utils（集成在 main 头部）

importosimportpandasaspdimportnumpyasnpfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAI,OpenAIEmbeddingsfromlangchain.vectorstoresimportFAISSfromlangchain.embeddingsimportHuggingFaceEmbeddingsfromlanggraph.graphimportStateGraph,ENDfromtypingimportTypedDict,List,Dict# 加载环境变量load_dotenv()# 初始化大模型llm=ChatOpenAI(api_key=os.getenv("OPENAI_API_KEY"),base_url=os.getenv("OPENAI_BASE_URL"),model_name=os.getenv("LLM_MODEL"),temperature=0.3)# 初始化向量化模型，本地开源向量模型，无需keyembedding=HuggingFaceEmbeddings(model_name="all‑MiniLM‑L6‑v2")# 读取商品数据集df=pd.read_csv("goods_data.csv")# 定义全局状态：多Agent之间传递的数据结构classAgentState(TypedDict):user_query:struser_profile:Dict recall_goods:List[Dict]rank_goods:List[Dict]final_recommend:List[Dict]explain:str

5.2 用户画像 Agent user_agent

接收用户查询，输出用户偏好标签

defuser_profile_agent(state:AgentState)->AgentState:prompt=f""" 根据用户的查询，提取用户电商购物偏好，输出json格式，包含字段： category(偏好类目),price_max(最高预算),tags(喜好标签列表) 用户输入：{state["user_query"]}"""res=llm.invoke(prompt)# 简单解析偏好profile=eval(res.content)state["user_profile"]=profilereturnstate

5.3 商品召回 Agent recall_agent

构建向量库、文本相似度召回候选商品

defbuild_vector_db():"""构建商品向量数据库"""texts=df.apply(lambdax:f"{x['name']}{x['category']}{x['tag']}",axis=1).tolist()db=FAISS.from_texts(texts,embedding,metadatas=df.to_dict("records"))db.save_local("vector_db")returndb# 初始化向量库vector_db=build_vector_db()defrecall_agent(state:AgentState)->AgentState:user_text=str(state["user_profile"])search=vector_db.similarity_search(user_text,k=20)candidates=[doc.metadatafordocinsearch]state["recall_goods"]=candidatesreturnstate

5.4 排序打分 Agent rank_agent

综合评分、销量、价格匹配度加权打分

defrank_agent(state:AgentState)->AgentState:goods_list=state["recall_goods"]profile=state["user_profile"]max_price=profile.get("price_max",9999)scored=[]foritemingoods_list:score=0# 商品基础评分权重 50%score+=float(item["score"])*0.5# 销量权重30%score+=min(item["sales"]/5000,1)*3# 价格低于预算加分iffloat(item["price"])<=float(max_price):score+=2scored.append({"score_total":score,**item})# 降序排序scored_sort=sorted(scored,key=lambdax:x["score_total"],reverse=True)state["rank_goods"]=scored_sortreturnstate

5.5 策略过滤 Agent policy_agent

商品黑名单过滤、截取 Top‑5 推荐结果 + 生成推荐理由

defpolicy_agent(state:AgentState)->AgentState:goods=state["rank_goods"]# 简单过滤示例：4.3分以下商品剔除filter_goods=[gforgingoodsiffloat(g["score"])>=4.4]top5=filter_goods[:5]state["final_recommend"]=top5# LLM生成推荐解释文案prompt=f"""基于用户偏好{state['user_profile']}，给用户解释为什么推荐下面商品：{top5}，简短易懂"""exp=llm.invoke(prompt)state["explain"]=exp.contentreturnstate

5.6 入口对话 Agent + LangGraph 搭建多 Agent 工作流 [main.py](main.py)

defchat_entry(state:AgentState):returnstate# 构建多Agent流程图workflow=StateGraph(AgentState)# 注册各个智能体节点workflow.add_node("chat_entry",chat_entry)workflow.add_node("user_agent",user_profile_agent)workflow.add_node("recall_agent",recall_agent)workflow.add_node("rank_agent",rank_agent)workflow.add_node("policy_agent",policy_agent)# 设置节点流转顺序workflow.set_entry_point("chat_entry")workflow.add_edge("chat_entry","user_agent")workflow.add_edge("user_agent","recall_agent")workflow.add_edge("recall_agent","rank_agent")workflow.add_edge("rank_agent","policy_agent")workflow.add_edge("policy_agent",END)# 编译运行图app=workflow.compile()# 测试入口if__name__=="__main__":input_state={"user_query":"我想买一条夏天穿的高腰显瘦的女装短裤，预算90以内","user_profile":{},"recall_goods":[],"rank_goods":[],"final_recommend":[],"explain":""}res=app.invoke(input_state)print("=====最终推荐商品=====")forginres["final_recommend"]:print(f'{g["name"]}价格:{g["price"]}评分:{g["score"]}')print("\n推荐理由：\n",res["explain"])

六、系统运行流程 & 效果

1. 运行python main.py

2. 用户自然语言输入购物需求

3. Agent1 提取用户预算、品类、标签偏好

4. Agent2 向量相似度召回一批候选商品

5. Agent3 多维度加权打分排序

6. Agent4 过滤劣质商品、截取 Top5，生成推荐解释

七、多 Agent 可视化图片获取方式

方式 1：LangGraph 自带流程图

在代码末尾添加，自动生成工作流图片

fromPILimportImage img=app.get_graph().draw_mermaid_png()withopen("agent_workflow.png","wb")asf:f.write(img)

运行后项目文件夹生成agent_workflow.png，即为多 Agent 流程图。

方式 2‑架构手绘示意图

1. 矩形框画出 5 个 Agent

2. 使用箭头串联调用顺序

3. 标注向量数据库、用户输入、商品数据集

八、进阶优化方向

1. 增加记忆 Agent：存储用户历史浏览记录，实现长期用户画像

2. 工具 Agent：对接 MySQL 商品数据库、Redis 热门商品缓存

3. 多轮对话 Agent：支持用户反馈 “价格太贵、换款式”，Agent 循环重新召回推荐

4. 替换本地大模型（Ollama‑Qwen、Llama3），脱离外网 API

5. 增加 A/B 测试 Agent、冷启动 Agent、流量风控 Agent 扩充多智能体集群

九、常见问题

1. FAISS 向量库报错：确认安装 faiss‑cpu；首次运行自动生成 vector_db 文件夹

2. 大模型调用失败：检查密钥、接口地址，优先切换国内大模型接口

3. 解析 JSON 失败：调低 temperature，强制 LLM 严格输出 JSON 格式

我把全部代码打包成可直接下载的完整项目目录结构，封装为一键初始化脚手架压缩文本，包含完整项目初始配置，新建项目直接粘贴即可完成初始化，适配前文代码与部署逻辑。需要的兄弟微信扫码添加，我挨个发~