_1791885195.png?x-oss-process=image/resize,h_300/format,webp/quality,q_80)
在前面三篇文章中，我们从 Agent 的记忆难题出发，讨论了 Cognee 的处理机制，以及 CittaBase 提供的多模一体化计算能力。在这一篇中，我们将进入实际操作：部署 Cognee、配置模型，上传资料并完成一次真实检索。
CittaBase、Cognee 后端与 Web 界面部署在同一台服务器上，对话模型和 Embedding 模型通过 API 调用。
| 项目 | 要求 |
|---|---|
| 操作系统 | Rocky Linux 9，x86_64；推荐 Rocky Linux 9.7 |
| 建议配置 | 16 核 CPU、32 GB 内存、200 GB 可用磁盘空间 |
| 安装权限 | root，或具备 sudo 权限 |
| 运行环境 | Python 3.11、Node.js 22，下载安装 |
| 模型服务 | OpenAI 兼容 API 的对话模型与 Embedding 模型 |
| 网络 | 服务器可访问系统软件源与模型 API；Mindmap 需要浏览器访问 d3js.org |
推荐使用一台全新的服务器，并且确保 55432、8000、3000 端口未被占用。此外，还需提前准备好两类模型的 API 基础地址、模型名称、API Key，以及 Embedding 输出维度，本次安装部署基于 Qwen text-embedding-v4 模型 + deepseek-v4-flash，Qwen text-embedding-v4 生成 Embedding，DeepSeek 负责内容理解、实体关系抽取和答案生成。
以下命令在服务器上以 root 执行。
创建目录：
mkdir -p /opt/install将配套的两个安装文件上传至该目录：
ymatrix-ai-1.0.0-1.rocky9.x86_64.rpm
cognee-cittabase.tar.gzcd /opt/install
dnf module enable -y nodejs:22
dnf install -y nodejs python3.11 python3.11-pip tar gzip
dnf install -y ./ymatrix-ai-1.0.0-1.rocky9.x86_64.rpm
node --version各个命令需逐条执行，确认成功后再继续。Node.js 的版本应为 v22.x.x 。
应用包已包含 Python 依赖、预构建的 Web 界面与安装工具，无需自行编译。解压并检查包结构：
cd /opt/install
tar -xzf cognee-cittabase.tar.gz
cd cognee-cittabase
python3.11 setup.py --check-package当输出 Package layout check passed 后，执行bash setup.sh
然后根据安装器提示填写模型参数：
| 参数 | 内容 |
|---|---|
| Chat API address | 对话模型 API 基础地址 |
| Chat model name | 对话模型名称 |
| Chat API key | 对话模型密钥 |
| Embedding API address | Embedding API 基础地址 |
| Embedding model name | Embedding 模型名称 |
| Embedding API key | Embedding 模型密钥 |
| Embedding dimension | 与模型实际输出一致的向量维度 |
输入密钥时终端不回显字符，粘贴后按 Enter 即可。数据库密码由安装器自动生成，应用部署、数据库初始化和服务启动也由安装器完成。
安装成功后会输出如下信息：
Installation complete.
Database: running
API: ready
UI: ready如果安装中断，需要保留错误信息与现场进行排查，不建议随意删除数据目录或直接重跑安装器。
默认服务仅监听服务器本机，需要通过 SSH 隧道访问：在本地电脑上执行以下命令，替换服务器地址和登录账号：
ssh -N -o ExitOnForwardFailure=yes -L 3000:127.0.0.1:3000 -L 8000:127.0.0.1:8000 root@YOUR_SERVER_IP然后在浏览器中访问：http://localhost:3000，登录之后在 Local instance 页面保留预填的本地评估登录信息，点击 Sign in。
注意，这套配置用于私有评估，无需开放公网应用端口。正式共享访问时，需另行配置认证、TLS 与网络策略。
首次验证推荐使用安装包内附带的示例文档：/opt/install/cognee-cittabase/examples/first-test.pdf，可以先将服务器上的示例 PDF 下载到本机，再通过浏览器上传。
在 Web 界面中依次操作：
1.进入 Brain，点击 Create brain 或 New brain，创建 first-test。
2.打开 first-test，点击 Add files，上传示例 PDF。
3.等待自动处理完成（此步骤取决于大模型的处理速度），再打开 Mindmap 查看知识关系。
4.进入 Search → Company Brain，选择 first-test Dataset，输入下面的问题。
What is the maintenance interval for the Orion-147 cooling pump?
预期回答为 45 days，与示例文档中的维护周期一致。如有来源引用，一并与原文核对。
当前交付界面在上传后会自动执行 Cognify，无需手动触发。处理过程会调用模型 API；
在服务器上检查服务状态：
/opt/cognee/bin/cognee-control status
数据库、API、UI 均正常运行，且文档处理和问答验证通过后，即可导入自己的资料。也可以沿用前文的 MARS3 Bucket 文档，验证同一个问题：
MARS3 Bucket 如何减少 Redistribute Motion，并让下游算子进行本地计算？
以下命令在服务器上以 root 执行：
| 操作 | 命令 |
|---|---|
| 查看状态 | /opt/cognee/bin/cognee-control status |
| 启动服务 | /opt/cognee/bin/cognee-control start |
| 停止服务 | /opt/cognee/bin/cognee-control stop |
| 重启服务 | /opt/cognee/bin/cognee-control restart |
| 更新模型配置或密钥 | /opt/cognee/bin/cognee-control configure |
启停操作需要避开文档处理期间。服务已配置为开机启动，服务器重启后重新建立 SSH 隧道即可访问。
configure 支持更新密钥和对话模型配置，保存后会重启 API。已有向量与 Embedding 模型相关，因此工具会阻止直接修改 Embedding 模型、地址与维度；此类调整需要另行安排向量重建或迁移。
当遇到问题时，优先检查以下几项：
| 现象 | 检查项 |
|---|---|
| 无法访问界面 | 服务状态、SSH 隧道、本机端口是否被占用 |
| 界面可打开，但操作失败 | 隧道是否同时转发 3000 与 8000 端口 |
| 文档处理失败 | 模型地址、名称、密钥、额度及网络连接 |
| 回答为空或无关 | 文档是否处理完成，是否选择正确的 Dataset |
至此，CittaBase 与 Cognee 的单机环境已完成部署，并通过示例文档验证了知识构建与检索问答。后续可以导入产品手册、运维记录或业务规范，结合原文检查召回内容与知识关系，评估其在实际任务中的使用效果。
