跳到正文
曾亮懿 ZengLiangYi Blog

本地 AI 知识库快速上手:安装部署、会话导入与检索

在本地部署 Node.js 与 Electron AI 编程知识库:使用 ChatCrystal CLI 依次验证安装启动、生成与向量双模型配置、多客户端会话导入、结构化摘要与语义检索。

阅读约 5 分钟
目录 展开 收起

把 AI 编程对话变成可以再次使用的笔记,需要先把几条链路分别跑通:工具能启动、历史能导入、模型能处理、笔记能检索。第一次使用时,先验证一条记录,比直接批量处理全部历史更容易定位问题。

本文以 ChatCrystal 0.6.1、提交 7642768 为基准,使用本机 CLI 工作流。模型下载和运行时间取决于网络与硬件,这里不承诺几分钟内完成。

先选择使用入口

桌面应用和 npm 包不是同一个安装产物。想通过窗口浏览对话,可以从 GitHub Releases 选择适合平台的桌面发行包;本文下面的命令用于 npm CLI。

npm 包的文件清单包含编译后的服务端和共享模块,没有 client/dist。服务只有找到前端构建目录才会提供网页。因此,安装 npm 包后不能把“访问 3721 端口一定出现完整界面”当作验收条件;CLI 可以直接调用 API 完成下面的操作。

安装并检查命令

该版本的包声明要求 Node.js 24 或更高。先检查运行环境,再安装本文对应版本:

node --version
npm install -g chatcrystal@0.6.1
crystal --version
crystal --help

如果找不到 crystal,先检查 npm prefix -g 对应的全局可执行文件目录是否在 PATH,以及当前终端是否使用刚才安装的 Node 环境。重新打开终端后再验证,避免在多个 Node 管理器之间反复重装。

启动本机服务

crystal serve -d
crystal status

默认服务端口是 3721。运行路径实现默认把数据放在用户目录的 .chatcrystal/data,DATA_DIR 可以在启动前指定其他位置。记录实际目录,后续备份需要同时考虑数据库、配置与向量索引。

本文使用默认本机端口与隐式本机连接。端口冲突时,先确认占用端口的进程,协调使用默认端口。当前 CLI 会拒绝显式指定的、没有报告云模式的 loopback 连接,因此不能用改成 3722 再传 --base-url 的方式承诺跑通本机流程。已有远端连接配置也会改变命令的目标,应先查看状态中的连接信息。

分别配置生成与检索模型

语言模型负责生成结构化笔记,Embedding 模型负责生成检索向量。下面使用当前默认配置中出现的两个 Ollama 模型,作为可复现的示例,选型仍需结合自己的硬件和内容评估。

安装并启动 Ollama 后:

ollama pull qwen2.5:7b
ollama pull nomic-embed-text
crystal config get

确认两类配置都指向本机模型服务。对于需要重设的配置:

crystal config set llm.provider ollama
crystal config set llm.baseURL http://localhost:11434
crystal config set llm.model qwen2.5:7b
crystal config set embedding.provider ollama
crystal config set embedding.baseURL http://localhost:11434
crystal config set embedding.model nomic-embed-text
crystal config test

已有索引时,部分 Embedding 变更会要求确认;先阅读警告和安排重建,不要直接追加 --confirm。连接测试分别报告 LLM 与 Embedding 的结果,应两项都看。它测试的是短请求,不能证明长对话的摘要质量或完整索引一定成功。

本地存储也不等于全部推理都在本地。远端端点会收到相应文本;详细边界见本地优先与隐私。两类模型的配置区别见 LLM 与 Embedding。

导入并选择一条对话

crystal import
crystal status
crystal summarize

空数据库首次启动时,初始化代码会尝试插入演示会话与笔记。demo- 开头的记录不是你的导入结果,状态总数大于零也不能证明真实历史已导入。

默认本机导入扫描已启用的数据源,将可解析的历史写入应用数据库,不会仅因为导入成功就生成笔记。无参数的 summarize 会列出待摘要对话,便于选择 ID。导入结果中的扫描、跳过和错误各有含义;对话数为零时,核对工具是否留下历史、数据源路径与服务进程的读取权限。

如果命令显示远端上传确认,先核对目标地址。云模式下,CLI 会扫描本机历史并上传解析后的对话,不能把这个过程解释成本机数据库导入。

生成笔记并验证搜索

从真实导入结果中选一条包含具体问题、处理办法与验证或可复用经验的对话,用它的 ID 替换下面的示例位置,不要选择演示记录:

crystal summarize <conversation-id>
crystal notes list
crystal --json search "曾经讨论的具体错误或解决方法" --limit 5

这里的搜索使用 --json,保证走传递 --limit 的非交互分支,返回值是结果数组。先检查摘要是否保留问题条件、解决办法和验证结果,再查看搜索返回的笔记。摘要流程还会先经过经验门槛:不满足条件的对话可以正常变为 filtered,返回空结果且不生成笔记,这与模型调用失败不同。选择下一条有实际经验的历史继续验证。会生成笔记,不代表向量已经可用;摘要、向量处理和查询端点都可能分别失败。搜索结果为空,也可能来自检索阈值或表达差异,不能只凭一次查询判断数据丢失。

成功标准是一条可定位的原始对话、一条内容可信的笔记,以及一次能读懂来源的检索结果。完成这条链路后,再考虑批量摘要和 Agent 接入。平时查看服务状态用 crystal serve status,停止本机后台服务用 crystal serve stop;停止服务不会代替数据备份。

分享:

相关文章

导出 AI 结构化笔记到 Obsidian:Markdown 格式与标签转换

分页导出 ChatCrystal 笔记,用稳定 ID 建立 Obsidian 双向链接,并明确快照、人工编辑和增量同步之间的边界。

曾亮懿 曾亮懿
阅读约 6 分钟
#ChatCrystal #Node.js #知识管理

研发团队技术知识库共享方案:访问令牌与审批流设计

设计研发团队 AI 技术知识库共享与权限隔离方案:区分实例级访问令牌与成员读写角色,在网关层验证只读检索、敏感内容脱敏与批量入库人工审批流。

曾亮懿 曾亮懿
阅读约 5 分钟
#ChatCrystal #知识管理 #架构

从文章到代码

到我的 GitHub 看看 ChatCrystal、KeelDesk、n8n 工作流和日常学习记录,欢迎交流实现细节。