把一句自然语言变成购物车里的真实订单这个链路比表面看起来复杂得多。这次要拆解的项目叫From LLM to shopping cart (Portugal)从名字就能看出它的定位以葡萄牙市场为落地场景打通 LLM 和购物车系统之间的完整链路。用户说“我要两瓶波特酒送人的挑平价一点的”Agent 需要把这句话拆成意图、商品、数量和偏好再调用购物车接口完成加购最后把结果组合成自然语言回复给用户。这类项目最值得关注的不是模型本身而是工程链路怎么做意图解析、怎么让 LLM 稳定输出结构化参数、怎么设计工具调用、怎么对接真实购物车 API、怎么处理批量任务。项目标签里的 Portugal 也不是装饰它意味着必须处理葡萄牙语指令、本地商品命名、欧元计价和区域用户习惯这些是很多 LLM demo 不会暴露的细节。如果你正在做 LLM Agent、智能客服、区域电商或采购助理这类应用这篇文章可以直接照做一遍。下面我会按本地部署的思路把环境准备、项目结构、启动方式、功能测试、接口调用、批量任务和性能观察完整过一遍最后给出一份可直接复用的排查清单和实践建议。1. 核心能力速览先按这个项目的定位整理一张能力表。下面的内容是按“自然语言到购物车”这类 Agent 项目的通用形态整理的实际仓库的结构可能略有差异以你拉下来的代码为准。能力项说明项目类型LLM Agent 应用实战面向电商购物车场景核心链路自然语言输入 - 意图识别与槽位抽取 - 工具调用 - 购物车 API - 结果回执目标市场葡萄牙市场pt-PT可扩展到多语言区域LLM 接入OpenAI 兼容接口支持在线大模型或本地推理服务具体模型按实际环境配置购物车服务独立 REST API项目内部通过 Tool Calling / Function Calling 调用多轮对话支持基于会话上下文的购物车修改、删除、数量调整批量任务支持商品清单批量导入、批量加购等场景接口能力提供 HTTP 接口便于接入客服、网页或小程序等前端启动方式命令行 FastAPI 服务依赖环境Python 3.10可选用 Docker、Redis 存储会话状态这个项目最核心的点是“从 LLM 到购物车”这条链路的完整性。它不是只做文本生成也不是只写购物车 CRUD而是把两者用 Agent 的方式接起来。你输入一段自然语言后面经过模型理解、结构化输出、工具调用、接口执行、状态回写最后购物车真实发生了变化这个过程里任何一环断了整个体验都会失败。2. 适用场景与使用边界2.1 这个项目适合谁从技术栈和场景看这个项目最适合三类人。第一类是正在做 LLM Agent 落地的人。很多 Agent demo 只跑在玩具数据上这里却要求模型输出精确的购物车参数并且真实调用外部接口能训练你做完整工具链路的能力。第二类是电商后端或购物车系统的开发者。如果你的系统希望增加自然语言入口这个项目是一个很合适的参考实现商品加购、会话管理、批量导入这些模块都能直接借鉴。第三类是运营和客服工具开发者。面向葡萄牙语或其他小语种市场的电商更需要这种“自然语言直达操作”的交互方式能减少用户输入成本也能降低客服重复劳动。2.2 能解决的问题从产品角度说这个项目解决的是搜索和加购的效率问题。传统电商购物车需要用户先搜索、再筛选、再选择规格、再点加入购物车而这里用户直接说一句“我要一箱矿泉水送到里斯本站点自取”就可以完成。对于重复购买、批量采购这类场景效率提升非常明显。从技术角度说它解决了“意图到结构化参数”的稳定转换问题。LLM 直接返回自然语言是不可靠的只有把它约束成 JSON 或函数调用购物车接口才能消费。这也是 Agent 类项目最关键的工程点。2.3 不适合什么场景这个项目不适合作为高并发交易系统直接上线。购物车本身就是低频写操作如果要做秒杀、大规模并发加购还需要额外做消息队列、限流、缓存等一系列架构升级Agent 层的吞吐和稳定性不会比传统接口更好。也不适合让 LLM 直接处理支付结算。模型可能理解错金额、选错折扣、重复扣款支付环节必须由专门的服务在边界外处理LLM 最多只能表达结算意图不能执行扣款操作。2.4 使用边界与合规提醒购物车数据涉及用户个人偏好、收货地址、历史订单如果面向葡萄牙或欧盟地区用户就要注意 GDPR 下的数据保护要求比如数据最小化原则、用户删除权、日志脱敏等。支付信息和敏感凭据不能进入 LLM 上下文。商品价格、库存、促销信息也不能让模型自由发挥必须从权威数据源读取。涉及订单自动生成时建议保留人工确认环节尤其是大额订单、礼品订单或代付订单。项目本身是技术验证用的生产环境一定要把安全边界补上。3. 环境准备与前置条件3.1 系统与语言环境这个项目是典型的 Python 应用推荐用 Python 3.10 以上版本Windows、Linux、macOS 都可以跑。建议用 venv 或 conda 建一个独立环境避免和本机其他项目依赖冲突。python --version pip --version如果没有任何输出或版本过低先装 Python。下面是一个通用的一键创建虚拟环境的方式python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate3.2 LLM 推理服务这个项目一般通过 OpenAI 兼容接口访问 LLM所以你需要先确定模型服务从哪里来。有两种常见选择在线 API比如各类国产或海外大模型平台的 OpenAI 兼容端点配置好api_key和base_url即可。本地推理如果本机有 N 卡也可以部署一个本地服务比如通过 Ollama 或 vLLM 起一个 OpenAI 兼容的服务模型名按实际环境配置。本地推理的好处是数据不出内网适合测试阶段反复调用。缺点是模型较小的时候葡萄牙语理解和结构化输出能力会弱一些需要多做几次校验。3.3 购物车后端服务项目还需要一个购物车服务。生产环境自然是自己的电商后端测试阶段可以先用一个简单的模拟服务或者项目自带的cart_client.py里默认的本地服务。关键接口一般会包含添加购物车项修改购物车项数量删除购物车项查询购物车没有真实购物车服务时可以把cart_client.py先接到一个本地 JSON 文件或者 SQLite 上跑通链路后再换真实接口。3.4 端口规划启动前先检查端口避免冲突。常见的是 LLM 服务的 8000、Agent 服务的 8001、购物车服务的 9000。可以按实际环境调整。# Linux / macOS lsof -i :8000 # Windows netstat -ano | findstr :8000如果端口被占用要么杀掉占用进程要么在配置里更换端口。多进程长期运行时建议用 Docker 把几类服务隔离部署。4. 安装部署与启动方式4.1 项目结构参考一个完整的“LLM 到购物车”项目目录大致长这样llm-to-cart/ ├── app.py # FastAPI 服务入口 ├── agent.py # LLM Agent 核心逻辑 ├── cart_client.py # 购物车 API 客户端 ├── requirements.txt # Python 依赖 ├── .env # 环境变量 ├── data/ │ └── products_pt.json # 葡萄牙市场商品测试数据 └── tests/ └── test_cart_flows.py # 链路测试这是一个通用结构具体以实际仓库为准。我建议第一次先把项目跑起来再逐步看agent.py和cart_client.py的代码。4.2 安装依赖pip install openai pydantic fastapi uvicorn requests python-dotenv如果项目自带requirements.txt直接用pip install -r requirements.txt安装失败时通常是因为网络源不稳定可以切换国内镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple4.3 配置环境变量.env文件一般长这样LLM_API_KEYEMPTY LLM_BASE_URLhttp://localhost:8000/v1 LLM_MODELqwen2.5:7b CART_API_BASEhttp://127.0.0.1:9000 CART_SESSION_REDISredis://127.0.0.1:6379/0如果你用的是在线 API把LLM_BASE_URL换成平台的地址LLM_API_KEY换成真实的 key模型名换成对应模型。如果项目里没有.env你可以自己创建一份并在代码里用python-dotenv加载。4.4 启动购物车模拟服务先启动购物车后端保证后续 Agent 调用有地方可去。假设cart_server.py是模拟购物车服务python cart_server.py --host 127.0.0.1 --port 9000启动成功后验证一下健康检查接口curl http://127.0.0.1:9000/health返回{status: ok}一类结果就说明购物车服务起来了。4.5 启动 Agent 服务购物车服务起来后再启动 Agent 服务uvicorn app:app --host 0.0.0.0 --port 8001注意这里如果传0.0.0.0局域网内其他机器也可以访问。如果只想本机调试建议改成uvicorn app:app --host 127.0.0.1 --port 8001启动后看到Uvicorn running on http://127.0.0.1:8001说明服务正常。4.6 服务健康检查可以用 curl 验证 Agent 服务curl http://127.0.0.1:8001/docsFastAPI 默认会返回 Swagger 文档页面直接在浏览器打开http://127.0.0.1:8001/docs可以看到所有接口也能直接点击调试对刚开始排查问题非常有用。5. 功能测试与效果验证项目跑起来后先不要急着接前端一条条把核心链路过一遍。下面是一套可以直接执行的测试流程每条都写了输入、预期结果和判断标准。5.1 基础自然语言加购测试测试目的是验证“用户一句话 - LLM 结构化输出 - 购物车加购成功”这条主链路。输入示例把一盒 Pastel de Nata 加入购物车调用 Agent 接口后预期行为模型识别出商品是Pastel de Nata数量是 1。工具调用add_to_cart(product_id..., quantity1)。购物车服务返回加购成功。Agent 把结果回执转成自然语言。判断成功的标准很简单查购物车接口能看到对应商品和数量已经变化。失败排查如果模型识别不到商品说明商品名不在知识库或提示词里需要补充商品别名表。如果模型输出格式不对检查是否启用了 Function Calling或者提示词里有没有 JSON 格式约束。如果购物车接口报错检查CART_API_BASE配置和商品 ID 是否匹配。5.2 多轮对话修改购物车测试目的是验证会话上下文维护能力。第一轮输入加两瓶 Vinho do Porto 到购物车第二轮输入数量改成六瓶预期行为第二轮不是新增商品而是把之前那个Vinho do Porto的数量改成 6。判断标准购物车中该商品数量变为 6且购物车中没有重复新增一行。失败排查如果第二轮变成了新增商品说明会话上下文没有透传给 LLM检查请求里的session_id是否一致。如果上下文超过模型窗口可以考虑只保留最近几轮对话而不是全量拼接。5.3 葡萄牙语与多语言测试这是“Portugal”标签的关键测试。可以准备一组葡萄牙语测试句Quero adicionar um azeite ao carrinho. Adiciona 3 garrafas de vinho tinto. Qual é o preço total do carrinho?预期行为模型能理解消费类动词、商品词汇、数量词和货币表达并正确映射到购物车操作。判断标准购物车商品、数量、操作类型都正确并且回复语言与用户语言一致。失败排查葡萄牙语识别不理想时先检查使用的 LLM 对小语种的支持程度。公开测试里通用中文模型对葡萄牙语支持较弱可以换更强的多语言模型。葡萄牙本地习惯用pt-PT而巴西常用pt-BR两者在动词变位和用词上有差异。比如“carrinho”在两地都能用但更精细的表达需要做区域化测试。商品名建议维护一份本地化别名表比如azeite、vinho do porto、pastel de nata在测试数据里都要能查到。5.4 批量商品导入测试测试目的是验证批量任务能力。项目里一般会有一个批量导入入口示例商品清单[ {product_id: VIN-PORT-001, name: Douro Porto, price: 19.90}, {product_id: AZT-OLIVE-002, name: Portuguese Olive Oil, price: 8.50}, {product_id: PASTRY-NATA-003, name: Pastel de Nata Pack, price: 6.90} ]导入后用自然语言输入“把清单里的商品全部加入购物车”观察是否能够批量处理。判断标准三个商品都出现在购物车里数量正确没有重复或遗漏。失败排查批量任务卡住时先看日志是卡在 LLM 调用还是购物车接口调用。批量导入前要检查商品 ID 唯一性重复 ID 可能导致购物车数据错乱。数量过大的批量操作建议拆成小批次比如每批 10 个商品避免单次超时。5.5 异常输入测试这个测试最容易暴露 Agent 设计的薄弱点。建议至少准备以下几类异常输入输入类型示例预期行为商品不存在加一个不存在的商品明确提示商品不可用不调用购物车接口数量非法加零个商品 / 加负数拒绝执行并提示重新输入缺货加一件库存为 0 的商品提示用户缺货推荐替代选项意图不明确我想买点好东西主动追问而不是乱加购混合任务加两瓶酒并且查询总价先执行加购再返回最新购物车总价判断标准异常情况下不会向购物车写入错误数据并且回复是明确、可操作的不是跟用户绕圈子。失败排查如果模型在意图不明确时擅自加购说明提示词里缺少“不确定就追问”的约束。如果库存判断不准确购物车服务需要返回实时库存字段Agent 以接口结果为准不能靠 LLM 猜测。6. 接口 API 与批量任务6.1 核心接口设计项目对外暴露的接口一般集中在两类一类是 Agent 对话接口另一类是购物车操作接口。下面是一个通用设计参考方法路径说明POST/api/agent/chat接收用户消息返回 Agent 执行结果GET/api/cart/{session_id}查看某个会话的购物车POST/api/cart/items直接向购物车添加商品POST/api/batch/import批量导入商品清单接口路径以实际项目为准。重点是了解调用形态Agent 层接口负责理解自然语言购物车层接口负责执行操作。6.2 Agent Chat 接口调用示例先用 curl 验证接口curl -X POST http://127.0.0.1:8001/api/agent/chat \ -H Content-Type: application/json \ -d { message: 加两瓶波特酒到购物车, session_id: test-001 }期望返回结构类似{ session_id: test-001, ok: true, reply: 已把 2 瓶 Douro Porto 加入购物车当前购物车总价 39.80 €。, cart: { items: [ {product_id: VIN-PORT-001, name: Douro Porto, quantity: 2} ], total: 39.80 } }再给一段 Python 调用示例方便接到自己的工具或前端里import requests url http://127.0.0.1:8001/api/agent/chat payload { message: 加两瓶波特酒到购物车, session_id: test-001 } response requests.post(url, jsonpayload, timeout60) print(response.status_code) print(response.json())6.3 批量任务队列设计批量加购的场景建议不要一次把所有商品都塞给 LLM而是先在购物车层做商品解析再让 LLM 只处理歧义部分。一个更稳妥的流程是批量商品清单用 JSON 导入购物车服务。LLM 负责把用户一句话映射到清单里的商品 ID。如果匹配到多个候选商品再让用户确认而不是直接批量加购。批量任务还要考虑幂等性。给每次批量导入一个request_id重复提交时购物车服务通过请求 ID 去重避免重复加购。{ request_id: batch-20250415-001, items: [ {product_id: VIN-PORT-001, quantity: 5}, {product_id: AZT-OLIVE-002, quantity: 2} ] }批量任务运行过程中必须有日志。至少记录每批开始时间、成功数量、失败数量、失败原因、重试次数。没有日志的批量任务一旦卡住很难定位原因。6.4 失败重试建议LLM Agent 调用失败和购物车接口失败要分别处理。LLM 调用失败比如返回超时或空内容可以做一次重试但最多重试两三次避免造成接口压力和费用浪费。购物车接口失败要看错误码如果是 4xx说明参数有问题重试没有意义如果是 5xx可以间隔 2 秒、5 秒做指数退避重试。7. 资源占用与性能观察这个项目的主要资源消耗集中在三个地方LLM 推理、购物车 API 调用、会话状态存储。7.1 LLM 推理性能如果你用的是在线 API性能主要看延迟和 token 消耗。单次自然语言加购请求包含输入文本、系统提示词、函数定义和工具调用结果输入 token 会比单纯对话多一些。每次请求建议记录输入 token 数输出 token 数工具调用次数总耗时如果输出 token 特别多说明提示词约束不够模型在“废话”。如果输入 token 越来越高说明多轮上下文没有裁剪。7.2 本地模型显存与内存观察本地部署时重点看显存。观察显存最直接的方式是nvidia-sminvidia-smi -l 2-l 2表示每两秒刷新一次。启动本地 LLM 服务后可以观察模型占用的显存峰值。不同模型和量化方式的显存差异很大具体数值以你的显卡和配置为准。如果显存不够可以先降低并发数或者换更小的模型、使用量化版本。CPU 推理不是不行但一次完整加购链路通常包含多次模型调用CPU 模式下延迟会明显拉长更适合偶尔测试不太适合批量任务场景。7.3 批量任务的吞吐批量加购的吞吐瓶颈通常在购物车 API而不是 LLM。如果购物车 API 是本地模拟服务吞吐会很高如果连接的是真实电商系统就要注意限流频率避免一次性发送大量请求把上游打爆。建议批量任务做成异步队列一次处理一批商品而不是同步地等待每个商品都加购完再返回。异步的好处是失败能重试不会因为一个商品失败导致整个请求失败。7.4 降低资源占用的方法多轮对话只保留最近 N 轮减少输入 token。系统提示词和商品知识库分开管理商品信息不要全部塞进提示词。商品信息做缓存避免每次请求都重新查询。会话状态用 Redis 而不是内存保存重启服务不丢数据。限制 Agent 响应速度比如只允许单个用户串行请求避免突发并发把本地模型压垮。8. 常见问题与排查方法实际跑这类项目最常遇到的就是下面这几种问题直接对照排查。问题现象可能原因排查方式解决方案LLM 返回的不是结构化数据未启用 Function Calling或提示词里缺少输出约束查看 Agent 日志看返回内容是什么改用 Function Calling / JSON Schema并加一层解析重试葡萄牙语商品识别不准模型对小语种支持弱或商品名不在知识库输入葡语测试句查看模型输出换更强多语言模型维护商品别名表必要时接入 RAG加购后购物车没有变化LLM 解析到了商品 ID但购物车 API 调用失败查购物车服务日志和接口返回码检查商品 ID 是否存在、接口路径和认证参数多轮对话第二句变成新增商品会话上下文没有透传或上下文被截断检查请求里的 session_id打印拼接后的 prompt用 Redis 保存会话拼接最近 N 轮历史批量任务卡住不结束上游接口超时或失败重试无限循环看任务日志停在哪一步给每条任务设置超时和最大重试次数超出后标记失败Agent 服务端口被占用上一个进程没有退出Linux/macOS 用 lsofWindows 用 netstat更换端口或先结束占用进程本地推理显存不足模型过大或并发数过高nvidia-smi 看显存占用换量化版本、减小 batch、降低并发用户输入意图不明确时乱加购提示词缺少追问约束构造测试集跑一轮异常输入测试在系统提示词里明确“意图不确定时先追问”这张表覆盖了从模型层到接口层的主要故障点。遇到问题时先定位是哪一层的问题模型层、Agent 编排层、购物车服务层还是前端调用层。每一层都看日志问题会清楚很多。9. 最佳实践与使用建议9.1 结构化输出强约束LLM 直接输出自然语言不可靠购物车接口只接受结构化参数。建议统一用 Function Calling 或 JSON Schema并在代码里做一次解析校验。解析失败就自动重试一次重试仍失败则让模型把问题重新解释给用户而不是直接报错。9.2 商品映射用知识库不要靠模型猜模型可能知道“波特酒”是什么但它不一定知道你系统里对应的商品 ID。正确做法是维护一份商品别名映射表集中管理葡萄牙语名、英文名、别名、SKU、价格、库存。如果商品数量很大就接入 RAG让模型先从商品向量库里检索再调用购物车接口。9.3 加购操作设计成幂等购物车加购接口要支持幂等。用户重复点击、网络重试、批量任务重跑时不能因为重复请求而多次加购。实现方式很简单在请求里带request_id或使用严格的(session_id, product_id)唯一约束。9.4 保留人工确认与审计日志涉及订单生成的操作要在用户确认后再执行尤其是大额订单和跨店订单。所有 LLM 指令、工具调用、接口返回都要记录日志方便用户投诉时回溯。数据敏感部分要脱敏用户 ID、地址、手机号等字段不要原样输出到模型上下文。9.5 安全边界支付与权限隔离购物车可以自动操作但支付必须独立出来。Agent 只能表达“用户想结算”的意图实际扣款由支付服务完成。如果系统里有权限体系还要注意普通用户只能操作自己的购物车不能通过构造请求修改别人的会话数据。9.6 合规提醒面向葡萄牙或欧盟用户时需要遵守 GDPR 对个人数据的处理要求。会话记录不要永久保存给用户提供删除入口。测试阶段使用真实用户数据时要先做脱敏和授权确认。商品价格、库存、促销信息要从权威数据源读取不能让模型自由发挥。9.7 准备一套回归测试集项目会随着功能迭代变复杂建议把上面的测试用例整理成一个自动化回归测试文件每次改完代码就跑一遍。测试集要包含葡萄牙语用例、多轮修改用例、批量用例和异常输入用例能提前发现大部分链路问题。# tests/test_cart_flows.py 示例结构 def test_add_pastel_de_nata(): # 输入 把一盒 Pastel de Nata 加入购物车 # 断言购物车出现对应商品且数量为 1 pass def test_update_quantity_in_dialogue(): # 第一轮加两瓶酒第二轮改成六瓶 # 断言购物车数量为 6 且不新增行 pass def test_product_not_found(): # 输入不存在的商品名 # 断言购物车未被修改回复提示商品不可用 pass10. 总结与下一步这个项目最值得尝试的一点是它把“LLM 理解自然语言”和“真实购物车操作”完整接在一起。它不是停留在文本生成的 demo而是能真实改变购物车状态的 Agent 链路。建议你先验证第一项核心能力用一句自然语言完成加购然后查购物车确认商品确实写入成功。这一步通了后面的多轮修改、批量导入、多语言支持都会顺利很多。最容易踩的坑有三个LLM 返回了非结构化数据、多轮对话上下文丢失、商品 ID 在映射环节匹配错误。这三个问题只要在项目初期就做好约束和日志后面基本不会有大麻烦。后续扩展可以往这几个方向走接入 MCP 工具协议让 Agent 能调用更多购物车和订单能力接入 RAG 商品知识库解决大规模商品检索把葡萄牙语测试集扩展到更多小语种场景再从购物车延伸到订单、优惠券、库存预占等完整交易链路。如果你正在规划 LLM Agent 类的项目这个购物车场景是一个很好的切入角度建议收藏备用跑通之后再往生产环境逐步加安全边界和人工审核。 从LLM到购物车：葡萄牙市场自然语言加购Agent实战
把一句自然语言变成购物车里的真实订单这个链路比表面看起来复杂得多。这次要拆解的项目叫From LLM to shopping cart (Portugal)从名字就能看出它的定位以葡萄牙市场为落地场景打通 LLM 和购物车系统之间的完整链路。用户说“我要两瓶波特酒送人的挑平价一点的”Agent 需要把这句话拆成意图、商品、数量和偏好再调用购物车接口完成加购最后把结果组合成自然语言回复给用户。这类项目最值得关注的不是模型本身而是工程链路怎么做意图解析、怎么让 LLM 稳定输出结构化参数、怎么设计工具调用、怎么对接真实购物车 API、怎么处理批量任务。项目标签里的 Portugal 也不是装饰它意味着必须处理葡萄牙语指令、本地商品命名、欧元计价和区域用户习惯这些是很多 LLM demo 不会暴露的细节。如果你正在做 LLM Agent、智能客服、区域电商或采购助理这类应用这篇文章可以直接照做一遍。下面我会按本地部署的思路把环境准备、项目结构、启动方式、功能测试、接口调用、批量任务和性能观察完整过一遍最后给出一份可直接复用的排查清单和实践建议。1. 核心能力速览先按这个项目的定位整理一张能力表。下面的内容是按“自然语言到购物车”这类 Agent 项目的通用形态整理的实际仓库的结构可能略有差异以你拉下来的代码为准。能力项说明项目类型LLM Agent 应用实战面向电商购物车场景核心链路自然语言输入 - 意图识别与槽位抽取 - 工具调用 - 购物车 API - 结果回执目标市场葡萄牙市场pt-PT可扩展到多语言区域LLM 接入OpenAI 兼容接口支持在线大模型或本地推理服务具体模型按实际环境配置购物车服务独立 REST API项目内部通过 Tool Calling / Function Calling 调用多轮对话支持基于会话上下文的购物车修改、删除、数量调整批量任务支持商品清单批量导入、批量加购等场景接口能力提供 HTTP 接口便于接入客服、网页或小程序等前端启动方式命令行 FastAPI 服务依赖环境Python 3.10可选用 Docker、Redis 存储会话状态这个项目最核心的点是“从 LLM 到购物车”这条链路的完整性。它不是只做文本生成也不是只写购物车 CRUD而是把两者用 Agent 的方式接起来。你输入一段自然语言后面经过模型理解、结构化输出、工具调用、接口执行、状态回写最后购物车真实发生了变化这个过程里任何一环断了整个体验都会失败。2. 适用场景与使用边界2.1 这个项目适合谁从技术栈和场景看这个项目最适合三类人。第一类是正在做 LLM Agent 落地的人。很多 Agent demo 只跑在玩具数据上这里却要求模型输出精确的购物车参数并且真实调用外部接口能训练你做完整工具链路的能力。第二类是电商后端或购物车系统的开发者。如果你的系统希望增加自然语言入口这个项目是一个很合适的参考实现商品加购、会话管理、批量导入这些模块都能直接借鉴。第三类是运营和客服工具开发者。面向葡萄牙语或其他小语种市场的电商更需要这种“自然语言直达操作”的交互方式能减少用户输入成本也能降低客服重复劳动。2.2 能解决的问题从产品角度说这个项目解决的是搜索和加购的效率问题。传统电商购物车需要用户先搜索、再筛选、再选择规格、再点加入购物车而这里用户直接说一句“我要一箱矿泉水送到里斯本站点自取”就可以完成。对于重复购买、批量采购这类场景效率提升非常明显。从技术角度说它解决了“意图到结构化参数”的稳定转换问题。LLM 直接返回自然语言是不可靠的只有把它约束成 JSON 或函数调用购物车接口才能消费。这也是 Agent 类项目最关键的工程点。2.3 不适合什么场景这个项目不适合作为高并发交易系统直接上线。购物车本身就是低频写操作如果要做秒杀、大规模并发加购还需要额外做消息队列、限流、缓存等一系列架构升级Agent 层的吞吐和稳定性不会比传统接口更好。也不适合让 LLM 直接处理支付结算。模型可能理解错金额、选错折扣、重复扣款支付环节必须由专门的服务在边界外处理LLM 最多只能表达结算意图不能执行扣款操作。2.4 使用边界与合规提醒购物车数据涉及用户个人偏好、收货地址、历史订单如果面向葡萄牙或欧盟地区用户就要注意 GDPR 下的数据保护要求比如数据最小化原则、用户删除权、日志脱敏等。支付信息和敏感凭据不能进入 LLM 上下文。商品价格、库存、促销信息也不能让模型自由发挥必须从权威数据源读取。涉及订单自动生成时建议保留人工确认环节尤其是大额订单、礼品订单或代付订单。项目本身是技术验证用的生产环境一定要把安全边界补上。3. 环境准备与前置条件3.1 系统与语言环境这个项目是典型的 Python 应用推荐用 Python 3.10 以上版本Windows、Linux、macOS 都可以跑。建议用 venv 或 conda 建一个独立环境避免和本机其他项目依赖冲突。python --version pip --version如果没有任何输出或版本过低先装 Python。下面是一个通用的一键创建虚拟环境的方式python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate3.2 LLM 推理服务这个项目一般通过 OpenAI 兼容接口访问 LLM所以你需要先确定模型服务从哪里来。有两种常见选择在线 API比如各类国产或海外大模型平台的 OpenAI 兼容端点配置好api_key和base_url即可。本地推理如果本机有 N 卡也可以部署一个本地服务比如通过 Ollama 或 vLLM 起一个 OpenAI 兼容的服务模型名按实际环境配置。本地推理的好处是数据不出内网适合测试阶段反复调用。缺点是模型较小的时候葡萄牙语理解和结构化输出能力会弱一些需要多做几次校验。3.3 购物车后端服务项目还需要一个购物车服务。生产环境自然是自己的电商后端测试阶段可以先用一个简单的模拟服务或者项目自带的cart_client.py里默认的本地服务。关键接口一般会包含添加购物车项修改购物车项数量删除购物车项查询购物车没有真实购物车服务时可以把cart_client.py先接到一个本地 JSON 文件或者 SQLite 上跑通链路后再换真实接口。3.4 端口规划启动前先检查端口避免冲突。常见的是 LLM 服务的 8000、Agent 服务的 8001、购物车服务的 9000。可以按实际环境调整。# Linux / macOS lsof -i :8000 # Windows netstat -ano | findstr :8000如果端口被占用要么杀掉占用进程要么在配置里更换端口。多进程长期运行时建议用 Docker 把几类服务隔离部署。4. 安装部署与启动方式4.1 项目结构参考一个完整的“LLM 到购物车”项目目录大致长这样llm-to-cart/ ├── app.py # FastAPI 服务入口 ├── agent.py # LLM Agent 核心逻辑 ├── cart_client.py # 购物车 API 客户端 ├── requirements.txt # Python 依赖 ├── .env # 环境变量 ├── data/ │ └── products_pt.json # 葡萄牙市场商品测试数据 └── tests/ └── test_cart_flows.py # 链路测试这是一个通用结构具体以实际仓库为准。我建议第一次先把项目跑起来再逐步看agent.py和cart_client.py的代码。4.2 安装依赖pip install openai pydantic fastapi uvicorn requests python-dotenv如果项目自带requirements.txt直接用pip install -r requirements.txt安装失败时通常是因为网络源不稳定可以切换国内镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple4.3 配置环境变量.env文件一般长这样LLM_API_KEYEMPTY LLM_BASE_URLhttp://localhost:8000/v1 LLM_MODELqwen2.5:7b CART_API_BASEhttp://127.0.0.1:9000 CART_SESSION_REDISredis://127.0.0.1:6379/0如果你用的是在线 API把LLM_BASE_URL换成平台的地址LLM_API_KEY换成真实的 key模型名换成对应模型。如果项目里没有.env你可以自己创建一份并在代码里用python-dotenv加载。4.4 启动购物车模拟服务先启动购物车后端保证后续 Agent 调用有地方可去。假设cart_server.py是模拟购物车服务python cart_server.py --host 127.0.0.1 --port 9000启动成功后验证一下健康检查接口curl http://127.0.0.1:9000/health返回{status: ok}一类结果就说明购物车服务起来了。4.5 启动 Agent 服务购物车服务起来后再启动 Agent 服务uvicorn app:app --host 0.0.0.0 --port 8001注意这里如果传0.0.0.0局域网内其他机器也可以访问。如果只想本机调试建议改成uvicorn app:app --host 127.0.0.1 --port 8001启动后看到Uvicorn running on http://127.0.0.1:8001说明服务正常。4.6 服务健康检查可以用 curl 验证 Agent 服务curl http://127.0.0.1:8001/docsFastAPI 默认会返回 Swagger 文档页面直接在浏览器打开http://127.0.0.1:8001/docs可以看到所有接口也能直接点击调试对刚开始排查问题非常有用。5. 功能测试与效果验证项目跑起来后先不要急着接前端一条条把核心链路过一遍。下面是一套可以直接执行的测试流程每条都写了输入、预期结果和判断标准。5.1 基础自然语言加购测试测试目的是验证“用户一句话 - LLM 结构化输出 - 购物车加购成功”这条主链路。输入示例把一盒 Pastel de Nata 加入购物车调用 Agent 接口后预期行为模型识别出商品是Pastel de Nata数量是 1。工具调用add_to_cart(product_id..., quantity1)。购物车服务返回加购成功。Agent 把结果回执转成自然语言。判断成功的标准很简单查购物车接口能看到对应商品和数量已经变化。失败排查如果模型识别不到商品说明商品名不在知识库或提示词里需要补充商品别名表。如果模型输出格式不对检查是否启用了 Function Calling或者提示词里有没有 JSON 格式约束。如果购物车接口报错检查CART_API_BASE配置和商品 ID 是否匹配。5.2 多轮对话修改购物车测试目的是验证会话上下文维护能力。第一轮输入加两瓶 Vinho do Porto 到购物车第二轮输入数量改成六瓶预期行为第二轮不是新增商品而是把之前那个Vinho do Porto的数量改成 6。判断标准购物车中该商品数量变为 6且购物车中没有重复新增一行。失败排查如果第二轮变成了新增商品说明会话上下文没有透传给 LLM检查请求里的session_id是否一致。如果上下文超过模型窗口可以考虑只保留最近几轮对话而不是全量拼接。5.3 葡萄牙语与多语言测试这是“Portugal”标签的关键测试。可以准备一组葡萄牙语测试句Quero adicionar um azeite ao carrinho. Adiciona 3 garrafas de vinho tinto. Qual é o preço total do carrinho?预期行为模型能理解消费类动词、商品词汇、数量词和货币表达并正确映射到购物车操作。判断标准购物车商品、数量、操作类型都正确并且回复语言与用户语言一致。失败排查葡萄牙语识别不理想时先检查使用的 LLM 对小语种的支持程度。公开测试里通用中文模型对葡萄牙语支持较弱可以换更强的多语言模型。葡萄牙本地习惯用pt-PT而巴西常用pt-BR两者在动词变位和用词上有差异。比如“carrinho”在两地都能用但更精细的表达需要做区域化测试。商品名建议维护一份本地化别名表比如azeite、vinho do porto、pastel de nata在测试数据里都要能查到。5.4 批量商品导入测试测试目的是验证批量任务能力。项目里一般会有一个批量导入入口示例商品清单[ {product_id: VIN-PORT-001, name: Douro Porto, price: 19.90}, {product_id: AZT-OLIVE-002, name: Portuguese Olive Oil, price: 8.50}, {product_id: PASTRY-NATA-003, name: Pastel de Nata Pack, price: 6.90} ]导入后用自然语言输入“把清单里的商品全部加入购物车”观察是否能够批量处理。判断标准三个商品都出现在购物车里数量正确没有重复或遗漏。失败排查批量任务卡住时先看日志是卡在 LLM 调用还是购物车接口调用。批量导入前要检查商品 ID 唯一性重复 ID 可能导致购物车数据错乱。数量过大的批量操作建议拆成小批次比如每批 10 个商品避免单次超时。5.5 异常输入测试这个测试最容易暴露 Agent 设计的薄弱点。建议至少准备以下几类异常输入输入类型示例预期行为商品不存在加一个不存在的商品明确提示商品不可用不调用购物车接口数量非法加零个商品 / 加负数拒绝执行并提示重新输入缺货加一件库存为 0 的商品提示用户缺货推荐替代选项意图不明确我想买点好东西主动追问而不是乱加购混合任务加两瓶酒并且查询总价先执行加购再返回最新购物车总价判断标准异常情况下不会向购物车写入错误数据并且回复是明确、可操作的不是跟用户绕圈子。失败排查如果模型在意图不明确时擅自加购说明提示词里缺少“不确定就追问”的约束。如果库存判断不准确购物车服务需要返回实时库存字段Agent 以接口结果为准不能靠 LLM 猜测。6. 接口 API 与批量任务6.1 核心接口设计项目对外暴露的接口一般集中在两类一类是 Agent 对话接口另一类是购物车操作接口。下面是一个通用设计参考方法路径说明POST/api/agent/chat接收用户消息返回 Agent 执行结果GET/api/cart/{session_id}查看某个会话的购物车POST/api/cart/items直接向购物车添加商品POST/api/batch/import批量导入商品清单接口路径以实际项目为准。重点是了解调用形态Agent 层接口负责理解自然语言购物车层接口负责执行操作。6.2 Agent Chat 接口调用示例先用 curl 验证接口curl -X POST http://127.0.0.1:8001/api/agent/chat \ -H Content-Type: application/json \ -d { message: 加两瓶波特酒到购物车, session_id: test-001 }期望返回结构类似{ session_id: test-001, ok: true, reply: 已把 2 瓶 Douro Porto 加入购物车当前购物车总价 39.80 €。, cart: { items: [ {product_id: VIN-PORT-001, name: Douro Porto, quantity: 2} ], total: 39.80 } }再给一段 Python 调用示例方便接到自己的工具或前端里import requests url http://127.0.0.1:8001/api/agent/chat payload { message: 加两瓶波特酒到购物车, session_id: test-001 } response requests.post(url, jsonpayload, timeout60) print(response.status_code) print(response.json())6.3 批量任务队列设计批量加购的场景建议不要一次把所有商品都塞给 LLM而是先在购物车层做商品解析再让 LLM 只处理歧义部分。一个更稳妥的流程是批量商品清单用 JSON 导入购物车服务。LLM 负责把用户一句话映射到清单里的商品 ID。如果匹配到多个候选商品再让用户确认而不是直接批量加购。批量任务还要考虑幂等性。给每次批量导入一个request_id重复提交时购物车服务通过请求 ID 去重避免重复加购。{ request_id: batch-20250415-001, items: [ {product_id: VIN-PORT-001, quantity: 5}, {product_id: AZT-OLIVE-002, quantity: 2} ] }批量任务运行过程中必须有日志。至少记录每批开始时间、成功数量、失败数量、失败原因、重试次数。没有日志的批量任务一旦卡住很难定位原因。6.4 失败重试建议LLM Agent 调用失败和购物车接口失败要分别处理。LLM 调用失败比如返回超时或空内容可以做一次重试但最多重试两三次避免造成接口压力和费用浪费。购物车接口失败要看错误码如果是 4xx说明参数有问题重试没有意义如果是 5xx可以间隔 2 秒、5 秒做指数退避重试。7. 资源占用与性能观察这个项目的主要资源消耗集中在三个地方LLM 推理、购物车 API 调用、会话状态存储。7.1 LLM 推理性能如果你用的是在线 API性能主要看延迟和 token 消耗。单次自然语言加购请求包含输入文本、系统提示词、函数定义和工具调用结果输入 token 会比单纯对话多一些。每次请求建议记录输入 token 数输出 token 数工具调用次数总耗时如果输出 token 特别多说明提示词约束不够模型在“废话”。如果输入 token 越来越高说明多轮上下文没有裁剪。7.2 本地模型显存与内存观察本地部署时重点看显存。观察显存最直接的方式是nvidia-sminvidia-smi -l 2-l 2表示每两秒刷新一次。启动本地 LLM 服务后可以观察模型占用的显存峰值。不同模型和量化方式的显存差异很大具体数值以你的显卡和配置为准。如果显存不够可以先降低并发数或者换更小的模型、使用量化版本。CPU 推理不是不行但一次完整加购链路通常包含多次模型调用CPU 模式下延迟会明显拉长更适合偶尔测试不太适合批量任务场景。7.3 批量任务的吞吐批量加购的吞吐瓶颈通常在购物车 API而不是 LLM。如果购物车 API 是本地模拟服务吞吐会很高如果连接的是真实电商系统就要注意限流频率避免一次性发送大量请求把上游打爆。建议批量任务做成异步队列一次处理一批商品而不是同步地等待每个商品都加购完再返回。异步的好处是失败能重试不会因为一个商品失败导致整个请求失败。7.4 降低资源占用的方法多轮对话只保留最近 N 轮减少输入 token。系统提示词和商品知识库分开管理商品信息不要全部塞进提示词。商品信息做缓存避免每次请求都重新查询。会话状态用 Redis 而不是内存保存重启服务不丢数据。限制 Agent 响应速度比如只允许单个用户串行请求避免突发并发把本地模型压垮。8. 常见问题与排查方法实际跑这类项目最常遇到的就是下面这几种问题直接对照排查。问题现象可能原因排查方式解决方案LLM 返回的不是结构化数据未启用 Function Calling或提示词里缺少输出约束查看 Agent 日志看返回内容是什么改用 Function Calling / JSON Schema并加一层解析重试葡萄牙语商品识别不准模型对小语种支持弱或商品名不在知识库输入葡语测试句查看模型输出换更强多语言模型维护商品别名表必要时接入 RAG加购后购物车没有变化LLM 解析到了商品 ID但购物车 API 调用失败查购物车服务日志和接口返回码检查商品 ID 是否存在、接口路径和认证参数多轮对话第二句变成新增商品会话上下文没有透传或上下文被截断检查请求里的 session_id打印拼接后的 prompt用 Redis 保存会话拼接最近 N 轮历史批量任务卡住不结束上游接口超时或失败重试无限循环看任务日志停在哪一步给每条任务设置超时和最大重试次数超出后标记失败Agent 服务端口被占用上一个进程没有退出Linux/macOS 用 lsofWindows 用 netstat更换端口或先结束占用进程本地推理显存不足模型过大或并发数过高nvidia-smi 看显存占用换量化版本、减小 batch、降低并发用户输入意图不明确时乱加购提示词缺少追问约束构造测试集跑一轮异常输入测试在系统提示词里明确“意图不确定时先追问”这张表覆盖了从模型层到接口层的主要故障点。遇到问题时先定位是哪一层的问题模型层、Agent 编排层、购物车服务层还是前端调用层。每一层都看日志问题会清楚很多。9. 最佳实践与使用建议9.1 结构化输出强约束LLM 直接输出自然语言不可靠购物车接口只接受结构化参数。建议统一用 Function Calling 或 JSON Schema并在代码里做一次解析校验。解析失败就自动重试一次重试仍失败则让模型把问题重新解释给用户而不是直接报错。9.2 商品映射用知识库不要靠模型猜模型可能知道“波特酒”是什么但它不一定知道你系统里对应的商品 ID。正确做法是维护一份商品别名映射表集中管理葡萄牙语名、英文名、别名、SKU、价格、库存。如果商品数量很大就接入 RAG让模型先从商品向量库里检索再调用购物车接口。9.3 加购操作设计成幂等购物车加购接口要支持幂等。用户重复点击、网络重试、批量任务重跑时不能因为重复请求而多次加购。实现方式很简单在请求里带request_id或使用严格的(session_id, product_id)唯一约束。9.4 保留人工确认与审计日志涉及订单生成的操作要在用户确认后再执行尤其是大额订单和跨店订单。所有 LLM 指令、工具调用、接口返回都要记录日志方便用户投诉时回溯。数据敏感部分要脱敏用户 ID、地址、手机号等字段不要原样输出到模型上下文。9.5 安全边界支付与权限隔离购物车可以自动操作但支付必须独立出来。Agent 只能表达“用户想结算”的意图实际扣款由支付服务完成。如果系统里有权限体系还要注意普通用户只能操作自己的购物车不能通过构造请求修改别人的会话数据。9.6 合规提醒面向葡萄牙或欧盟用户时需要遵守 GDPR 对个人数据的处理要求。会话记录不要永久保存给用户提供删除入口。测试阶段使用真实用户数据时要先做脱敏和授权确认。商品价格、库存、促销信息要从权威数据源读取不能让模型自由发挥。9.7 准备一套回归测试集项目会随着功能迭代变复杂建议把上面的测试用例整理成一个自动化回归测试文件每次改完代码就跑一遍。测试集要包含葡萄牙语用例、多轮修改用例、批量用例和异常输入用例能提前发现大部分链路问题。# tests/test_cart_flows.py 示例结构 def test_add_pastel_de_nata(): # 输入 把一盒 Pastel de Nata 加入购物车 # 断言购物车出现对应商品且数量为 1 pass def test_update_quantity_in_dialogue(): # 第一轮加两瓶酒第二轮改成六瓶 # 断言购物车数量为 6 且不新增行 pass def test_product_not_found(): # 输入不存在的商品名 # 断言购物车未被修改回复提示商品不可用 pass10. 总结与下一步这个项目最值得尝试的一点是它把“LLM 理解自然语言”和“真实购物车操作”完整接在一起。它不是停留在文本生成的 demo而是能真实改变购物车状态的 Agent 链路。建议你先验证第一项核心能力用一句自然语言完成加购然后查购物车确认商品确实写入成功。这一步通了后面的多轮修改、批量导入、多语言支持都会顺利很多。最容易踩的坑有三个LLM 返回了非结构化数据、多轮对话上下文丢失、商品 ID 在映射环节匹配错误。这三个问题只要在项目初期就做好约束和日志后面基本不会有大麻烦。后续扩展可以往这几个方向走接入 MCP 工具协议让 Agent 能调用更多购物车和订单能力接入 RAG 商品知识库解决大规模商品检索把葡萄牙语测试集扩展到更多小语种场景再从购物车延伸到订单、优惠券、库存预占等完整交易链路。如果你正在规划 LLM Agent 类的项目这个购物车场景是一个很好的切入角度建议收藏备用跑通之后再往生产环境逐步加安全边界和人工审核。