安装与运维

本文档提供在客户基础设施中安装和运行 Parsewise 所需的信息：交付清单、环境要求、配置、安装步骤与运维。

1. 交付清单

交付清单是权利人云端实例所用的清单，其中写有该实例的地址和服务。应用之前，客户需将其调整为自己的部署：

• 镜像地址——改为交付仓库中的版本；
• 服务器和队列处理器清单中直接写入的值：FRONTEND_URL、SHOPS_DOMAIN、R2_ENDPOINT、R2_PUBLIC_URL、SMTP_HOST、SMTP_PORT、SMTP_USE_TLS、SMTP_START_TLS——改为自己的值（清单中的值优先于密钥中的值）；LLM_MODEL_QUERY——改为自己的模型名称或删除；
• 对密钥项 yandex-gpt-api-key、yandex-gpt-folder-id、yandex-maps-api-key 以及密钥 metrika-credentials 的引用——删除：它们只在云端实例中需要，缺少它们时集群中的 Pod 无法启动；
• 管理面板清单中——删除 NEXT_PUBLIC_API_URL 和 NEXT_PUBLIC_YM_COUNTER_ID，并设置第 3 节中的 PARSEWISE_* 参数；
• 密钥模板——填入自己的值并应用；其中包含交付清单读取的全部密钥，包括带有 SECRET_KEY、DOCS_USERNAME、DOCS_PASSWORD、EMAIL_FROM、INGRESS_LB_IP、LLM_BASE_URL 参数的 app-config-full；
• 客户不使用的服务的参数——删除：Robokassa 收款、Yandex Metrica；
• 存储桶访问策略示例——填入自己的存储桶名称和服务器账号；该示例针对 Yandex Object Storage 编写，在其他存储中用其自身工具设置相同的访问规则（第 2 节）；
• 对于 项目.域名 形式的项目地址——通过 cert-manager 在自己的 DNS 服务商处以 DNS01 验证签发 *.域名 证书，并在 06a-ingress-shops.yaml 中引用。

营销网站、文档和监控的清单不在交付范围内。

镜像以 OCI 归档形式交付，用于导入客户的镜像仓库，或通过权利人的镜像仓库获取。

镜像基于权利人的镜像源构建：构建时不从公共仓库下载基础镜像、Python 包和 npm 包。为处理音频和视频，服务器镜像包含 Debian 发行版中的 ffmpeg。安装和启动时不下载向量化模型。服务器和管理面板容器中的进程以非特权用户运行。

2. 环境要求

每个服务器和队列处理器 Pod 最多打开 40 个 PostgreSQL 连接。副本数较多时建议使用连接池，例如 PgBouncer 或 Odyssey。

计算资源

不含 Kubernetes 系统组件的资源请求总量：最小副本数时约 5.8 vCPU 和 14.9 GiB 内存，最大副本数时约 21.1 vCPU 和 47.6 GiB。节点必须能容纳内存请求为 2.5 GiB 的向量化 Pod。

权利人运行软件所用的配置：4–10 个节点，每个 4 vCPU、8 GiB，可自动添加节点；主库和向量库为独立的 PostgreSQL 15 集群，每个 2 vCPU、8 GiB，磁盘 20 GiB 并可自动扩展至 64 GiB；Valkey 7.2——2 vCPU、4 GiB。

3. 配置

服务器、队列处理器和调度器的参数通过环境变量设置——来自 Kubernetes 密钥或清单中的值（第 1 节）。三个部署获得相同的数据库、Redis 和对象存储连接参数。

必填

参数 FRONTEND_URL、EMAIL_FROM、SHOPS_DOMAIN 和 INGRESS_LB_IP 的默认值指向权利人的云端实例，因此在客户的部署中必须设置。

语言模型

软件不使用 OpenAI 公司的服务：“兼容 OpenAI”仅指 vLLM 及其他模型服务器所支持的编程接口格式。名称 openai 和 OPENAI_API_KEY 沿用该格式。

向量化

可选

管理面板与小部件

管理面板在启动时从容器环境变量读取部署参数。未设置的变量保留镜像构建时的值；值为空的变量会关闭相应功能。镜像以权利人云端实例的值构建——Yandex Metrica 计数器、Yandex ID 和 VK ID 应用、位于 releases.parsewise.ru 的小部件地址——因此在客户的部署中，PARSEWISE_YM_COUNTER_ID、PARSEWISE_YANDEX_CLIENT_ID 和 PARSEWISE_VK_CLIENT_ID 需显式设置为自己的值或空值，PARSEWISE_WIDGET_SCRIPT_URL 设置为小部件在客户基础设施中的地址。

小部件通过页面上 window.ParsewiseConfig 中的 apiUrl 参数获取编程接口服务器地址，同时获取项目标识 shopId；个人数据处理政策链接通过 privacyPolicyUrl 参数或项目设置获取。

同一份管理面板和小部件构建可在任何部署中使用：无需针对客户的地址和参数重新构建。

4. 安装

1. 准备 PostgreSQL：主库和向量库。向量库中必须提供 vector 类型。若没有，软件会执行 CREATE EXTENSION IF NOT EXISTS vector；若应用角色没有该权限，由数据库管理员预先执行 CREATE EXTENSION vector。
2. 准备 Redis 和兼容 S3 的对象存储存储桶；按第 2 节配置 CORS 规则和存储桶对象访问。
3. 将镜像导入集群可访问的镜像仓库，并在清单中填写其地址。
4. 创建命名空间以及包含第 3 节参数的密钥。
5. 在路由清单中填写编程接口和管理面板的域名，配置 TLS。
6. 应用清单。服务器启动时会创建主库中缺失的表，并应用镜像中包含的迁移；向量存储会创建自己的表和索引。
7. 将小部件文件放到客户的静态服务器或对象存储中。
8. 检查安装：
   • 所有 Pod 均处于就绪状态；向量化 Pod 加载模型最多需要三分钟；
   • 向编程接口服务器发送 GET /v1/public/health 请求返回 {"status": "ok"}；
   • 服务器日志中有 Alembic migrations applied (head reached) 一行，且没有 Alembic upgrade failed 消息和 pgvector 错误。

5. 开始使用

1. 登录管理面板并创建项目。
2. 设置助手人设：名称、头像和回答规则。
3. 填充知识库：上传文件、从文件导入商品或人员档案，或按链接接入数据源。
4. 邀请团队成员并分配角色。
5. 在网站或个人账户页面接入小部件：

<script>
  window.ParsewiseConfig = {
    shopId: "项目标识",
    apiUrl: "https://API服务器地址",
  };
</script>
<script async src="https://静态资源地址/widget.iife.js"></script>

管理面板的详细操作步骤见用户与管理员手册。

6. 运维