EPIR AI 助理后端使用说明

项目简介

EPIR Asystent 是一个为 EPIR Art Jewellery 商店设计的先进 AI 助理系统，专注于提供全面的客户行为分析和 AI 驱动的聊天体验。其核心后端服务实现了 Model Context Protocol (MCP)，允许大型语言模型 (LLM) 客户端以标准化的方式访问商店数据和功能，从而实现智能化的客户交互和购物辅助。

主要功能点

上下文服务 (RAG - Retrieval-Augmented Generation):
- 提供商品目录搜索、商店政策与常见问题解答 (FAQ) 等信息。
- 利用 Shopify MCP 作为主要数据源，并结合 Cloudflare Vectorize 进行语义搜索，确保回答的准确性和全面性。
工具调用 (Tools):
- 允许 LLM 执行操作，如查询产品详情、更新购物车内容、查看订单状态等。
- 这些功能通过 Shopify API 集成并以 MCP 工具的形式暴露，使得 LLM 能够与商店的业务逻辑进行交互。
会话管理:
- 利用 Cloudflare Durable Objects 维护持久化的用户会话和聊天历史，支持跨设备识别和个性化互动，从而提供更连贯的用户体验。
行为分析:
- 通过 Shopify Web Pixel 收集客户在商店中的行为事件（例如页面浏览、加入购物车等）。
- 这些数据存储于 Cloudflare D1 数据库，并结合 AI 进行客户意图识别和主动聊天激活，提升客户参与度。
JSON-RPC 协议:
- 服务器通过 JSON-RPC 2.0 协议与 LLM 客户端通信，接收并处理工具调用和信息查询请求，确保标准化的通信方式。

安装步骤

要运行 EPIR AI 助理后端，您需要一个 Cloudflare 账户，并安装 'wrangler' CLI 工具。

克隆仓库: 首先，将 'epir_asystent' GitHub 仓库克隆到您的本地机器：

git clone https://github.com/EPIRjewelry/epir_asystent.git
cd epir_asystent

配置 Cloudflare 环境:

安装 Wrangler CLI: 如果尚未安装，请安装 Cloudflare 'wrangler' CLI 并登录：

npm install -g wrangler
wrangler login

D1 数据库迁移: 进入 'workers/analytics-worker' 目录，执行以下命令创建和迁移 D1 数据库表：

cd workers/analytics-worker
wrangler d1 execute epir_art_jewellery --local --file=./schema-pixel-events-base.sql
wrangler d1 execute epir_art_jewellery --local --file=./schema-pixel-events-v3-heatmap.sql
wrangler d1 execute epir_art_jewellery --local --file=./schema-customer-sessions.sql
cd ../.. # 返回到 epir_asystent 根目录

部署 Workers: 分别进入 'workers/analytics-worker'、'workers/worker' 和 'workers/rag-worker' 目录，并为每个 Worker 执行 'wrangler deploy' 命令进行部署。

cd workers/analytics-worker && wrangler deploy && cd ../..
cd workers/worker && wrangler deploy && cd ../..
cd workers/rag-worker && wrangler deploy && cd ../..

设置环境变量和 Secrets: 在 Cloudflare Workers 仪表板中，为部署的 Worker 配置以下 Secrets (通过 'wrangler secret put <SECRET_NAME>') 和环境变量 (在 'wrangler.toml' 的 '[vars]' 部分)。确保您为所有相关的 Worker (特别是 'epir-art-jewellery-worker', 'epir-analityc-worker', 'epir-rag-worker') 配置了这些变量。
- 'GROQ_API_KEY': 您的 Groq AI API 密钥（必需）。
- 'SHOPIFY_APP_SECRET': 您的 Shopify 应用程序密钥，用于验证 Shopify App Proxy 请求的 HMAC 签名（必需）。
- 'SHOPIFY_ADMIN_TOKEN': 您的 Shopify Admin API 访问令牌（用于 GraphQL 后备查询）。
- 'SHOPIFY_STOREFRONT_TOKEN': 您的 Shopify Storefront API 访问令牌（可选）。
- 'SHOP_DOMAIN': 您的 Shopify 商店域名（例如 'your-store.myshopify.com'）。
- 'ALLOWED_ORIGIN': 允许进行跨域请求的来源域名（例如 'https://your-frontend.com' 或 '*'）。
- 此外，请确保 'wrangler.toml' 中正确配置了 Durable Objects ('SESSION_DO', 'RATE_LIMITER_DO', 'TOKEN_VAULT_DO')、D1 数据库 ('DB') 和 Service Bindings ('AI_WORKER', 'RAG_WORKER', 'ANALYTICS')。

部署 Shopify 扩展 (可选): 如果您希望使用完整的 Shopify 商店集成（例如前端聊天 UI 和行为追踪），请按照仓库的 'README.md' 指示部署 Shopify 应用程序扩展。这通常涉及 'shopify app deploy' 命令。

服务器配置 (MCP 客户端所需)

MCP 客户端需要配置 MCP 服务器的连接信息。以下是用于与 EPIR AI 助理后端建立连接的 JSON 配置示例：

{
  "server_name": "EPIR AI 助理后端",
  "command": "wrangler",
  "args": [
    "dev",
    "--port=8787",
    "./workers/worker/src/index.ts"
  ],
  "description": "EPIR AI 助理的本地开发服务器配置。此配置使用 Wrangler CLI 在本地启动 Cloudflare Worker，监听 8787 端口。它仅用于开发和测试目的，以便开发者能够在本地与 MCP 服务器交互。实际部署到生产环境后，MCP 客户端应直接连接到已部署 Worker 的公共 URL。",
  "variables": {
    "GROQ_API_KEY": {
      "description": "连接 Groq AI 服务的 API 密钥。这是必需的，用于 LLM 的文本生成和工具调用。",
      "required": true
    },
    "SHOPIFY_APP_SECRET": {
      "description": "Shopify 应用程序的密钥，用于验证 Shopify App Proxy 请求的 HMAC 签名。如果通过 Shopify App Proxy 访问，此密钥是必需的，以确保请求的安全性。",
      "required": true
    },
    "SHOPIFY_ADMIN_TOKEN": {
      "description": "访问 Shopify Admin API 的令牌。此令牌用于在 MCP 工具无法提供数据时，作为 GraphQL 后备查询的凭证。",
      "required": true
    },
    "SHOPIFY_STOREFRONT_TOKEN": {
      "description": "访问 Shopify Storefront API 的令牌。此令牌用于直接与 Shopify Storefront GraphQL API 交互，作为 MCP 调用的补充或备选方案。",
      "required": false
    },
    "SHOP_DOMAIN": {
      "description": "您的 Shopify 商店域名，例如 'your-store.myshopify.com'。这是连接到 Shopify API 和 MCP 端点的基本配置。",
      "required": true
    },
    "ALLOWED_ORIGIN": {
      "description": "允许进行跨域请求的来源。例如，您可以设置为 'https://your-frontend.com' 以限制访问，或设置为 '*' 以允许所有来源（仅限开发环境）。",
      "required": true
    }
  },
  "endpoints": {
    "mcp_tools": "/apps/assistant/mcp",
    "chat": "/apps/assistant/chat"
  }
}

请注意:

'command' 和 'args' 字段用于本地开发环境。
对于生产环境，MCP 客户端应直接连接到您部署的 Cloudflare Worker URL (例如，生产环境的 URL 可能是 'https://asystent.epirbizuteria.pl/apps/assistant/mcp' 或 'https://asystent.epirbizuteria.pl/chat')。

基本使用方法

一旦 MCP 服务器部署并运行，您的 LLM 客户端可以：

发送聊天消息: 向 '/chat' 或 '/apps/assistant/chat' 端点发送 POST 请求，请求体中包含用户消息和会话 ID。服务器将处理消息，调用相关工具或 RAG 获取上下文，并返回 AI 生成的回复。
- 示例请求体 (JSON):
```
{
  "message": "Jakie masz pierścionki?",
  "session_id": "test-session-123",
  "stream": true
}
```
- 'stream: true' 字段会指示服务器通过 Server-Sent Events (SSE) 流式传输回复。

调用 MCP 工具: 直接向 '/mcp/tools/call' 或 '/apps/assistant/mcp' 端点发送 JSON-RPC 请求，调用预定义的 MCP 工具（例如 'search_shop_catalog' 查询产品，'get_cart' 获取购物车信息）。

示例 JSON-RPC 请求体 (调用 'search_shop_catalog' 工具):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_shop_catalog",
    "arguments": {
      "query": "srebrna bransoletka",
      "first": 5
    }
  },
  "id": 1
}

接收流式响应: 如果 LLM 客户端在聊天请求中设置 'stream: true'，客户端将通过 Server-Sent Events (SSE) 接收 AI 生成的流式回复，以便实现更流畅的用户体验。

关键词