企业官网建设流程全解析

把一句自然语言变成购物车里的真实订单，这个链路比表面看起来复杂得多。这次要拆解的项目叫From LLM to shopping cart (Portugal)，从名字就能看出它的定位：以葡萄牙市场为落地场景，打通 LLM 和购物车系统之间的完整链路。用户说“我要两瓶波特酒，送人的，挑平价一点的”，Agent 需要把这句话拆成意图、商品、数量和偏好，再调用购物车接口完成加购，最后把结果组合成自然语言回复给用户。

这类项目最值得关注的不是模型本身，而是工程链路：怎么做意图解析、怎么让 LLM 稳定输出结构化参数、怎么设计工具调用、怎么对接真实购物车 API、怎么处理批量任务。项目标签里的 Portugal 也不是装饰，它意味着必须处理葡萄牙语指令、本地商品命名、欧元计价和区域用户习惯，这些是很多 LLM demo 不会暴露的细节。如果你正在做 LLM Agent、智能客服、区域电商或采购助理这类应用，这篇文章可以直接照做一遍。

下面我会按本地部署的思路，把环境准备、项目结构、启动方式、功能测试、接口调用、批量任务和性能观察完整过一遍，最后给出一份可直接复用的排查清单和实践建议。

1. 核心能力速览

先按这个项目的定位整理一张能力表。下面的内容是按“自然语言到购物车”这类 Agent 项目的通用形态整理的，实际仓库的结构可能略有差异，以你拉下来的代码为准。

这个项目最核心的点，是“从 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/activate

3.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/simple

4.3 配置环境变量

.env文件一般长这样：

LLM_API_KEY=EMPTY LLM_BASE_URL=http://localhost:8000/v1 LLM_MODEL=qwen2.5:7b CART_API_BASE=http://127.0.0.1:9000 CART_SESSION_REDIS=redis://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/docs

FastAPI 默认会返回 Swagger 文档页面，直接在浏览器打开http://127.0.0.1:8001/docs，可以看到所有接口，也能直接点击调试，对刚开始排查问题非常有用。

5. 功能测试与效果验证

项目跑起来后，先不要急着接前端，一条条把核心链路过一遍。下面是一套可以直接执行的测试流程，每条都写了输入、预期结果和判断标准。

5.1 基础自然语言加购测试

测试目的是验证“用户一句话 -> LLM 结构化输出 -> 购物车加购成功”这条主链路。

输入示例：

把一盒 Pastel de Nata 加入购物车

调用 Agent 接口后，预期行为：

1. 模型识别出商品是Pastel de Nata，数量是 1。
2. 工具调用add_to_cart(product_id="...", quantity=1)。
3. 购物车服务返回加购成功。
4. 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 设计的薄弱点。建议至少准备以下几类异常输入：

判断标准：异常情况下不会向购物车写入错误数据，并且回复是明确、可操作的，不是跟用户绕圈子。

失败排查：

• 如果模型在意图不明确时擅自加购，说明提示词里缺少“不确定就追问”的约束。
• 如果库存判断不准确，购物车服务需要返回实时库存字段，Agent 以接口结果为准，不能靠 LLM 猜测。

6. 接口 API 与批量任务

6.1 核心接口设计

项目对外暴露的接口一般集中在两类：一类是 Agent 对话接口，另一类是购物车操作接口。下面是一个通用设计参考：

接口路径以实际项目为准。重点是了解调用形态：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, json=payload, timeout=60) print(response.status_code) print(response.json())

6.3 批量任务队列设计

批量加购的场景，建议不要一次把所有商品都塞给 LLM，而是先在购物车层做商品解析，再让 LLM 只处理歧义部分。一个更稳妥的流程是：

1. 批量商品清单用 JSON 导入购物车服务。
2. LLM 负责把用户一句话映射到清单里的商品 ID。
3. 如果匹配到多个候选商品，再让用户确认，而不是直接批量加购。

批量任务还要考虑幂等性。给每次批量导入一个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-smi：

nvidia-smi -l 2

-l 2表示每两秒刷新一次。启动本地 LLM 服务后，可以观察模型占用的显存峰值。不同模型和量化方式的显存差异很大，具体数值以你的显卡和配置为准。如果显存不够，可以先降低并发数，或者换更小的模型、使用量化版本。

CPU 推理不是不行，但一次完整加购链路通常包含多次模型调用，CPU 模式下延迟会明显拉长，更适合偶尔测试，不太适合批量任务场景。

7.3 批量任务的吞吐

批量加购的吞吐瓶颈通常在购物车 API，而不是 LLM。如果购物车 API 是本地模拟服务，吞吐会很高；如果连接的是真实电商系统，就要注意限流频率，避免一次性发送大量请求把上游打爆。

建议批量任务做成异步队列，一次处理一批商品，而不是同步地等待每个商品都加购完再返回。异步的好处是失败能重试，不会因为一个商品失败导致整个请求失败。

7.4 降低资源占用的方法

• 多轮对话只保留最近 N 轮，减少输入 token。
• 系统提示词和商品知识库分开管理，商品信息不要全部塞进提示词。
• 商品信息做缓存，避免每次请求都重新查询。
• 会话状态用 Redis 而不是内存保存，重启服务不丢数据。
• 限制 Agent 响应速度，比如只允许单个用户串行请求，避免突发并发把本地模型压垮。

8. 常见问题与排查方法

实际跑这类项目，最常遇到的就是下面这几种问题，直接对照排查。

这张表覆盖了从模型层到接口层的主要故障点。遇到问题时先定位是哪一层的问题：模型层、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(): # 输入不存在的商品名 # 断言购物车未被修改，回复提示商品不可用 pass

10. 总结与下一步

这个项目最值得尝试的一点，是它把“LLM 理解自然语言”和“真实购物车操作”完整接在一起。它不是停留在文本生成的 demo，而是能真实改变购物车状态的 Agent 链路。建议你先验证第一项核心能力：用一句自然语言完成加购，然后查购物车确认商品确实写入成功。这一步通了，后面的多轮修改、批量导入、多语言支持都会顺利很多。

最容易踩的坑有三个：LLM 返回了非结构化数据、多轮对话上下文丢失、商品 ID 在映射环节匹配错误。这三个问题只要在项目初期就做好约束和日志，后面基本不会有大麻烦。

后续扩展可以往这几个方向走：接入 MCP 工具协议让 Agent 能调用更多购物车和订单能力；接入 RAG 商品知识库解决大规模商品检索；把葡萄牙语测试集扩展到更多小语种场景；再从购物车延伸到订单、优惠券、库存预占等完整交易链路。如果你正在规划 LLM Agent 类的项目，这个购物车场景是一个很好的切入角度，建议收藏备用，跑通之后再往生产环境逐步加安全边界和人工审核。