这次我们来看一个非常克制的小项目思路：VelocityNote，一个带本地 AI 的极简 Markdown 笔记本。它的定位不是再造一个 All-in-One 笔记全家桶，而是把两件高频需求接起来——Markdown 写作编辑，加上跑在本地、不依赖云端的 AI 辅助能力。对于隐私敏感、经常写技术文档、喜欢把笔记文件牢牢攥在自己手里的用户来说，这种“本地优先”的路径比每次把内容丢给云端服务要踏实得多。
这类工具最值得关注的核心特点有几个：第一，Markdown 原生支持，语法高亮、实时渲染这些基本盘不会少；第二，本地 AI 推理，文本生成、总结、改写、问答都走本地模型，离线也能用；第三，轻量化，体积和启动成本都比大型知识库系统低不少；第四，数据本地化，笔记文件和配置都留在自己机器上，不会被平台锁定；第五，具备接口集成潜力，本地 AI 服务一旦暴露成 HTTP 接口，就能接进脚本或其他编辑器。下面这篇文章会带你过一遍这类工具从环境准备、部署启动、功能验证到接口调用的完整思路，并给出资源占用观察方法和常见问题排查表。
因为 VelocityNote 目前对外公开的信息还比较精简，本文会以“项目标题给出的能力边界”为准，所有具体命令和配置都采用通用模板形式，实际操作时需要以项目仓库的 README 和版本说明为准。如果你是 Markdown 重度用户、本地 AI 部署爱好者，或者正在评估“本地笔记 + 大模型”怎么落地，这篇可以直接收藏。
1. 核心能力速览
| 能力项 | 说明 |
|---|---|
| 项目类型 | 本地 Markdown 笔记本，集成本地 AI 能力 |
| 核心编辑能力 | Markdown 编辑、渲染、导入导出，具体功能以项目版本为准 |
| 本地 AI 能力 | 基于本地模型完成生成、总结、改写、问答等文本任务 |
| 是否需要云端 | 主要诉求是本地推理，离线可用，具体取决于模型加载方式 |
| 硬件要求 | 以本地模型体积为准，建议至少 16G 内存，有独立显卡更稳 |
| 支持平台 | 大概率通过本地 Web 服务访问，覆盖 Windows / macOS / Linux |
| 启动方式 | 常规 Node 或 Python 本地服务，浏览器访问 WebUI |
| API 能力 | 本地 AI 通常暴露为 HTTP 接口，具体路径以项目说明为准 |
| 批量任务 | 可通过接口对多篇 Markdown 笔记做批量处理和文本任务 |
| 适合场景 | 技术笔记、写作草稿、本地知识整理、离线 AI 辅助 |
这里有一件事必须先说清楚：项目标题只明确了两点，一个是 Markdown 笔记本，一个是 Local AI。因此上面表格里的“支持平台”“接口路径”“显存占用”都存在合理推测成分，最稳妥的判断是直接以 GitHub 仓库的 README、release 说明和实际运行日志为准。后面所有命令我都会标成“通用模板”，避免照抄之后启动失败。
2. 适用场景与使用边界
先聊适用场景。VelocityNote 这类“本地 Markdown 笔记 + 本地 AI”的组合，最适合下面几类人：
- 隐私敏感用户。个人日记、工作笔记、未公开的技术方案，不想经过云端大模型服务，本地推理能减少数据出本机的风险。
- Markdown 重度用户。日常写博客、写接口文档、维护 README，需要一套顺手的 Markdown 编辑器，同时希望 AI 能辅助润色和总结。
- 离线办公场景。在没有稳定外网的内网环境、通勤路上、机房或开发机上，本地模型依然可以提供服务。
- 喜欢折腾本地模型的人。已经有了 Ollama、llama.cpp 这类运行时，想找一个能和笔记结合的前端界面。
它不太适合什么场景？如果追求多端实时同步、团队多人协同批注、像 Notion 那样的大规模数据库结构，这类极简本地工具通常会吃力。同时它也不适合对 AI 效果要求极高、必须用超大参数模型的任务——本地机器能跑多少参数的模型，决定了你能得到多强的生成质量。
使用边界必须明确一条合规原则：本地 AI 只解决“算力在哪里跑”的问题，不解决“内容是否合规”的问题。不能因为模型是本地部署，就把未经授权的他人作品、包含个人敏感信息的文件、涉及肖像和声音的素材随意丢进去做生成和复制。部署在个人电脑上的服务只做本地测试；如果要开放给局域网或公网访问，必须加访问控制。发布或商用前，需要对 AI 生成内容做人工复核，确认不侵犯版权、不泄露隐私。
3. Markdown 笔记本与本地 AI 结合的几个关键技术点
很多人在选型时会忽略一点：Markdown 编辑器和本地 AI 不是简单拼在一起就完事，中间有几个比较关键的工程点。
第一是流式输出与 Markdown 渲染的同步问题。大模型在生成文本时通常采用流式返回，也就是内容不是一个整块瞬间出现，而是一个字一个字地“吐”出来。如果前端等全部生成完再渲染 Markdown，体验会很差；如果边接收边渲染，又容易遇到 Markdown 语法不完整导致的临时解析错误。常见处理思路是把流式文本按行缓冲，每收到一段完整内容就重新渲染一次。VelocityNote 如果在界面上做了流式输出，大概率会面对同一个问题：表格还在生成中、代码块还没闭合，预览区怎么保持不闪烁、不跳动。
第二是本地模型运行时的接入方式。现在本地大模型最常用的接入方案是走一个本地 HTTP 服务，再通过 OpenAI 兼容的/v1/chat/completions接口暴露给前端。笔记工具的职责是配置好接口地址、模型名和鉴权信息，然后把编辑器里的选中文本发送到本地服务，再把结果插回文档。好处是模型后端可以替换，今天用 CPU 跑小模型，明天换 GPU 跑大模型，前端不用改。
第三是数据存储与全文字检索。Markdown 文件本身是纯文本，最理想的存储方式就是按目录存放.md文件，数据库只负责索引。这样用户即使不打开 VelocityNote，也能用 VS Code、命令行直接阅读和修改笔记，不会被私有格式锁住。全文检索能力大多依赖倒排索引或嵌入式 SQLite FTS，本地笔记数量大的时候，搜索速度会直接影响体验。
第四是常用 Markdown 特性的支持程度。从编辑体验角度，至少要覆盖标题层级、加粗斜体、行内代码与代码块、表格、引用、链接、图片、任务列表，以及 GFM 特性如删除线、自动链接。更进一步可能还需要 Mermaid 流程图、数学公式 KaTeX 渲染、目录生成等功能。这些功能看着不复杂，但每个都是前端渲染层的额外工作量，也决定了 VelocityNote 能不能真正替代用户手头已有的 Markdown 编辑器。
第五是导入导出与文件监控。本地笔记本如果支持外部文件夹导入，那用户无缝迁移的难度会低很多。更成熟的方案会监听文件夹变化，外部用别的工具改动了.md文件，前端自动刷新。如果只支持自家数据目录、不支持自定义路径，灵活度会打折扣。
4. 环境准备与前置条件
在启动 VelocityNote 之前，先把环境检查清单过一遍。以下的版本号为通用推荐值，实际要以项目 README 为准。
4.1 操作系统与基础环境
- 操作系统：Windows 10/11、macOS、主流 Linux 发行版都可以先试；如果项目附带 Docker 镜像，Windows 也可以直接走容器。
- 终端工具：Windows 建议 PowerShell 或 Windows Terminal，macOS/Linux 用自带 Terminal。
- 包管理器：Node 项目需要 npm/yarn/pnpm，Python 项目需要 pip/uv/conda。
- 版本控制工具：建议安装 Git，用于克隆项目仓库。
- 浏览器：Chrome、Edge、Firefox 均可，尽量使用最新稳定版，避免旧浏览器对 Web Components 或者新版前端框架支持不足。
4.2 本地 AI 运行时与模型
既然项目名里带 Local AI，那大概率不能只装前端，还需要一个本地模型运行时。比较常见的选择是 Ollama、llama.cpp、LM Studio，它们都能在本机启动一个 OpenAI 兼容接口。如果你之前已经装过其中任意一个，直接复用即可。
| 运行时 | 特点 | 适用机器 |
|---|---|---|
| Ollama | 安装简单、模型管理方便，社区模型多 | CPU 和 NVIDIA/AMD 显卡都能用 |
| llama.cpp | 纯 C/C++ 实现，量化支持好，资源占用相对低 | 低内存、无独显的老机器可试 |
| LM Studio | 图形界面，模型下载和配置直观 | 不熟悉命令行的用户优先考虑 |
模型体积是环境准备阶段最容易忽略的部分。一个 7B 参数的量化模型大约需要 4G 到 6G 磁盘空间，运行时还需要数 GB 内存；13B 或更大的模型对内存和显存的压力会快速上升。如果只跑笔记本辅助，优先选体积小的量化模型，比如 Qwen2.5 7B、Llama 3.1 8B 的 Q4_K_M 量化版本，先跑通再升级。
4.3 GPU 驱动与 CUDA
如果使用 NVIDIA 显卡并希望用 GPU 加速推理，需要提前确认驱动版本和 CUDA 环境。NVIDIA 驱动可以直接用nvidia-smi查看。注意的一点是：驱动支持的最高 CUDA 版本和运行时需要的 CUDA 版本是两回事，前者高不代表所有组件都能用。如果项目采用 Docker 方式启动，GPU 透传需要额外配置，不能直接docker run就完事。
4.4 端口检查
本地服务启动后默认跑在某个端口上，比如7860、3000、5173或8000等，具体以项目为准。启动前检查端口占用：
# Linux / macOS lsof -i :3000 # Windows PowerShell netstat -ano | findstr :3000如果端口被占用，要么结束占用进程，要么修改项目端口配置。
5. 安装部署与启动方式
由于项目具体仓库地址和安装方式目前没有公开细节，下面给出两套最常见的通用模板。读者按照实际项目情况替换即可。
5.1 方式一：Node 项目启动
# 克隆项目，具体地址以实际仓库为准 git clone https://example.com/velocitynote.git cd velocitynote # 安装依赖 npm install # 启动开发服务 npm run dev启动成功后，终端会显示本地访问地址，一般是http://localhost:3000或http://localhost:5173。打开浏览器后，如果能看到 Markdown 编辑界面，说明前端服务起来了。
5.2 方式二：Python 项目启动
# 克隆项目 git clone https://example.com/velocitynote.git cd velocitynote # 创建虚拟环境 python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 启动服务 python app.pyPython 服务启动后，终端会监听在http://127.0.0.1:8000或类似端口，浏览器访问即可。
5.3 配置本地 AI 模型服务
这里以 Ollama 作为示例。先把 Ollama 安装好并启动服务：
# 启动 Ollama 服务 ollama serve再拉取一个适合本机配置的模型：
# 拉取 7B 级量化模型 ollama pull qwen2.5:7b然后确认本地接口可访问：
curl http://127.0.0.1:11434/api/tags如果返回模型列表 JSON，说明本地 AI 服务正常。接下来在 VelocityNote 的配置页里填入模型服务地址和模型名称，例如：
ai_provider: ollama api_base: http://127.0.0.1:11434/v1 model: qwen2.5:7b注意：这里的配置键名是通用示例，不是 VelocityNote 的实际配置项，具体键名需要看项目配置文档。
5.4 Docker 启动
如果项目提供了 Dockerfile 或 docker-compose，可以走容器方式：
# docker-compose.yml 示例，需按项目实际调整 version: "3" services: velocitynote: image: velocitynote:latest ports: - "3000:3000" volumes: - ./data:/app/data启动命令：
docker compose up -d不管用哪种方式，第一目标都是“把界面跑起来”。这一步别急着调 AI，先把前端界面和项目目录结构确认清楚，再进入模型联调阶段。
6. 功能测试与效果验证
部署完之后，按下面的测试顺序走一遍，可以快速判断项目是否值得长期使用。测试时建议准备一个专门的测试目录，里面放不同格式的.md文件。
6.1 Markdown 基础编辑与渲染测试
测试目的：确认编辑器支持完整的 Markdown 语法，实时渲染不卡顿。
操作步骤：
- 新建一个笔记，粘贴以下内容：
# 一级标题 ## 二级标题 这是一个**加粗**、*斜体*、`行内代码`的测试。 - 列表项一 - 列表项二 1. 有序列表一 2. 有序列表二 > 这是一个引用块。 [链接测试](https://example.com)- 观察编辑器预览区是否实时更新，标题、列表、引用等样式是否能正确渲染。
- 切换源码编辑和预览模式，检查光标定位是否准确。
预期结果：标题层级明显、列表缩进正确、链接可点击，编辑过程没有明显延迟。如果预览区空白，优先怀疑前端渲染依赖缺失或动态导入的组件加载失败。
6.2 代码块与表格测试
测试目的：确认 GFM 表格和代码块高亮能力。
| 功能 | 支持情况 | 备注 | | --- | --- | --- | | 代码高亮 | 待验证 | 测试 JS/Python/Shell | | 表格对齐 | 待验证 | 左右中对齐 | | 任务列表 | 待验证 | `- [ ]` 语法 | ```python def hello(): print("hello velocitynote")注意上面代码块里嵌了三个反引号，实际保存时也要保证 Markdown 代码块闭合。预期结果：表格渲染成整齐的表格样式，Python 代码有语法高亮，任务列表选项可以点击切换。 ### 6.3 Mermaid 流程图测试 如果项目支持 Mermaid 图表，粘贴下面的内容： ```markdown ```mermaid graph TD A[开始] --> B[写笔记] B --> C{需要 AI 帮助？} C -- 是 --> D[调用本地模型] C -- 否 --> E[保存笔记]预期结果：页面显示一个流程图，拓扑关系正确。如果显示原始代码而不是图表，说明当前版本没有内置 Mermaid 支持或者需要手动启用。 ### 6.4 本地 AI 文本生成测试 测试目的：验证编辑器和本地模型是否打通。 操作步骤： 1. 在笔记中选中一段英文或中文文本。 2. 点击 AI 辅助按钮，选择“总结”或“润色”。 3. 等待模型输出结果，观察结果是否插入到文档中。 预期结果：本地模型返回一段合理的改写后文本。如果长时间没有响应，先检查 Ollama 或其他本地模型服务是否在运行，再检查 VelocityNote 配置里的 API 地址和模型名是否匹配。 ### 6.5 流式输出测试 测试目的：确认 AI 生成内容时前端能够边生成边渲染。 操作步骤：发起一个较长文本的生成请求，输入提示词：“请写一篇 500 字的技术博客开头。”观察编辑区域是否出现逐渐变长的文字，而不是等待结束后一次性出现。 预期结果：文字逐渐出现，且 Markdown 语法在流式过程后能正常识别。如果内容是整块跳出来的，可能是前端没有启用流式解析，或者项目对普通文本插入没有做增量渲染。 ### 6.6 离线可用性测试 测试目的：确认拔掉外网之后核心功能仍然可用。 操作步骤：关闭 Wi-Fi，重新打开浏览器访问 VelocityNote 页面，再次进行文本生成测试。 预期结果：Markdown 编辑、保存、本地 AI 生成均正常。如果页面加载依赖了 CDN 前端资源，离线时可能出现样式丢失或组件加载失败，这一点会直接影响笔记本在隔离环境下的可用性，值得留意。 ### 6.7 数据持久化测试 测试目的：确认笔记文件保存到了正确位置，重启后不丢失。 操作步骤： 1. 新建一篇笔记，保存。 2. 记录笔记内容。 3. 重启服务，重新打开项目。 4. 确认笔记仍在列表，内容完整。 预期结果：笔记文件保存在本地目录中，重启后依然可访问。如果重启后内容消失，需要检查是数据库存储还是文件存储，以及工作目录是否发生变化。 ## 7. 接口 API 与批量任务 本地 AI 工具最实用的能力之一是接口开放程度。如果 VelocityNote 的本地 AI 服务是一个独立 HTTP 服务，可以从项目配置中找到接口地址。下面给出通用的 OpenAI 兼容接口调用示例。 ### 7.1 本地 AI 接口连通性测试 以 Ollama 兼容接口为例： ```bash curl http://127.0.0.1:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5:7b", "messages": [ {"role": "user", "content": "用一句话介绍本地 Markdown 笔记本"} ] }'如果返回类似下面的 JSON，说明本地模型接口正常：
{ "id": "chatcmpl-123", "object": "chat.completion", "model": "qwen2.5:7b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "本地 Markdown 笔记本是把笔记数据保存在本地，并用本地 AI 模型提供辅助写作的工具。" } } ] }7.2 Python 调用示例
给一个 Python 脚本，便于后续在批量任务中使用：
import requests import json api_url = "http://127.0.0.1:11434/v1/chat/completions" def ask_local_ai(prompt: str) -> str: payload = { "model": "qwen2.5:7b", "messages": [ {"role": "system", "content": "你是一个技术笔记助手，回答简洁准确。"}, {"role": "user", "content": prompt} ], "temperature": 0.7, "stream": False } response = requests.post(api_url, json=payload, timeout=120) response.raise_for_status() data = response.json() return data["choices"][0]["message"]["content"] if __name__ == "__main__": print(ask_local_ai("请总结下面这段 Markdown 的核心内容：本地 AI 推理、离线可用、隐私保护"))7.3 批量处理多篇笔记
如果 VelocityNote 允许通过接口或脚本批量处理笔记，一个常见的批量场景是对目录下的所有.md文件做摘要：
import pathlib import time notes_dir = pathlib.Path("./notes") summary_dir = pathlib.Path("./summaries") summary_dir.mkdir(exist_ok=True) for md_file in notes_dir.glob("*.md"): content = md_file.read_text(encoding="utf-8") prompt = f"请为以下笔记生成 100 字以内的摘要：\n\n{content[:2000]}" try: summary = ask_local_ai(prompt) output_file = summary_dir / f"{md_file.stem}_summary.md" output_file.write_text(summary, encoding="utf-8") print(f"处理完成: {md_file.name}") except Exception as exc: print(f"处理失败: {md_file.name}, 错误: {exc}") time.sleep(1)批量任务必须考虑失败重试和日志记录。上面这段只做了简单异常捕获，在实际场景中建议把每个文件的处理状态记录到 CSV 或日志文件里，避免中途失败后无法定位。
7.4 接口安全边界
本地 AI 接口默认监听127.0.0.1，只有本机可以访问。如果你在局域网里的另一台电脑上想访问笔记本界面或 AI 接口，需要把监听地址改成0.0.0.0，但这同时意味着局域网内其他设备都能访问。没有加鉴权就开放到公网是非常危险的做法，轻则被拿来刷算力，重则泄露笔记内容。稳妥做法是保持本机监听，或者通过 SSH 隧道做远程访问。
8. 资源占用与性能观察
本地 AI 项目最容易出现“界面启动很快，但一点 AI 按钮就卡住”的情况。这部分我们来梳理资源占用的观察方法和控制手段。
8.1 为什么本地模型比普通应用吃资源
本地模型推理时，内存和显存的消耗主要由三部分组成：模型权重、中间激活值、上下文缓存。模型权重在加载时一次分配，比如 7B 模型即使不推理，也会占好几个 GB；中间激活值和上下文长度直接相关，上下文越长，推理时内存占用越高。这就是为什么同一个模型，你让它总结短文本没事，让它一次分析 5000 字文档就可能爆内存。
8.2 观察方法
- Windows：打开任务管理器，在“性能”页看内存和 GPU 显存占用；有 NVIDIA 显卡时也可以用
nvidia-smi -l 1实时刷新显存使用情况。 - macOS：打开“活动监视器”，重点看内存页面的“内存压力”。
- Linux：使用
htop查看内存，使用nvidia-smi查看显存。 - 前端层面：打开浏览器开发者工具，切到 Performance 或 Memory 面板，可以看渲染进程对内存的消耗。
8.3 降低资源占用的常见手段
- 换量化模型。同样 7B 规模，Q4_K_M 比 F16 少用约一半内存，效果下降有限。
- 缩短上下文长度。如果接口支持
max_context或num_ctx参数，先设置为 2048，避免无谓的显存占用。 - 减少并发请求。本地模型不要同时开多个窗口请求，每个请求都会占用一份推理资源。
- 关闭 GPU 层的部分参数。llama.cpp 支持
--n-gpu-layers，可以只把一小部分层放到 GPU，其余用 CPU，降低显存压力。 - 生成时先测试单条记录，确认稳定后再加批量，不要一上来就 10 篇一起处理。
8.4 关于“显存多少才够”的判断
由于材料没有提供官方推荐配置，这里给出一个通用经验：7B 量化模型推理时，纯 CPU 运行需要约 8G 到 12G 内存，GPU 运行推荐 6G 以上显存，如果同时保留浏览器和笔记服务，内存建议 16G 起步。13B 及以上参数量模型需要的内存和显存会显著增加。上面数字只是基于常见本地部署经验的推测，实际占用以机器测试为准。最直接的办法是打开显存监控，然后发起一个长文本生成请求，观察峰值占用。
9. 常见问题与排查方法
本地部署工具的大部分问题都集中在依赖、端口、模型和渲染这四类。下面按现象整理一张排查表。
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 启动后浏览器打不开页面 | 服务未启动成功或端口被占用 | 查看终端日志，检查端口占用 | 修复依赖后重新启动，或更换端口 |
| 页面样式错乱 | 前端资源加载失败，CDN 依赖无法访问 | 浏览器开发者工具查看 Network 面板 | 检查是否有 CDN 依赖，配合项目离线部署方案 |
| 本地 AI 点击后无响应 | 模型服务未启动、接口地址或模型名错配 | 先用 curl 请求模型接口 | 启动模型运行时，检查配置项 |
| 模型响应速度很慢 | 模型过大、CPU 推理、上下文过长 | 观察内存和 CPU 占用 | 换更小模型、缩上下文、增加 GPU 层数 |
| 显存不足，进程被杀死 | 模型权重加上下文超过显存上限 | nvidia-smi 查看显存 | 换量化版本、减少 GPU 层、增大 swap |
| 流式输出时 Markdown 预览闪烁 | 前端没有正确处理非完整 Markdown 片段 | 检查流式渲染逻辑 | 按行缓冲，对未闭合代码块做降级处理 |
| 中文内容显示乱码 | 文件编码不是 UTF-8 | 检查文件编码和响应头 | 统一保存为 UTF-8，设置请求 charset |
| 保存后重启笔记丢失 | 数据目录未持久化，或工作目录发生变化 | 检查项目工作目录和配置文件 | 设置固定数据目录，Docker 部署时挂载 volume |
| 批量任务中途卡住 | 单次请求超时、模型服务崩掉、并发过高 | 查看服务日志和重试日志 | 增加超时时间，降低并发，逐条重试 |
| 端口被占用 | 本地已有其他服务占用同端口 | netstat/lsof 查看占用进程 | 杀掉占用进程或修改项目端口配置 |
遇到问题时，第一反应不应该是盲改配置，而是先看服务进程的终端输出，再看模型运行时的日志。日志里通常会有明确的错误码和堆栈信息，比任何经验都可靠。如果项目提供了 issue 模板，把环境信息、项目版本、完整日志发上去，维护者才可能帮你定位。
10. 最佳实践与使用建议
这里结合 Markdown 笔记和本地 AI 的常见使用方式，给出一套工程化建议。
10.1 目录结构管理
建议把笔记目录和模型目录分开管理：
velocitynote-data/ ├── notes/ # 笔记源文件 │ ├── 技术笔记/ │ ├── 工作日志/ │ └── 草稿/ ├── outputs/ # AI 生成结果 ├── configs/ # 项目配置 └── logs/ # 批量任务日志模型文件目录单独放在另一个磁盘或路径，比如models/，避免模型权重被笔记库同步工具误上传到云端。
10.2 第一次使用从小参数开始
先跑一个小模型，生成几十个字的文本，确认整条链路正常，然后再逐步加大上下文、换更大的模型、开批量任务。很多本地 AI 工具失败都不是项目本身的逻辑问题，而是配了一个本机跑不动的超大模型，导致系统直接卡死，连排查环境都没办法操作。
10.3 批量任务必须加日志和重试
批量处理笔记时，至少要记录三个字段：文件名、处理状态、失败原因。重试策略可以用简单的指数退避，比如第一次失败等 2 秒，第二次等 4 秒，最多重试 3 次。另外，批量任务不要一上来就全量处理，先拿 3 篇测试文件跑通，再处理正式文件。
10.4 接口服务的访问控制
本地 AI 服务如果无意对外开放，不要修改监听地址。需要远程访问时，优先选择 SSH 隧道或 Tailscale 这类方案，而不是直接把端口暴露到公网。任何未授权访问到本地模型服务，轻则是资源被占用，重则是笔记数据被读取。
10.5 合规要求
这是使用本地 AI 工具不可跳过的一条：涉及他人版权作品、个人隐私数据、肖像音频素材时，必须先确认授权再处理。本地推理不意味着可以随意复制和传播内容，生成和保存的产物也需要合法。接口服务如果被抓取滥用，同样可能带来法律风险。
10.6 保持项目可更新
本地工具最怕的问题是“装的时候能用，装完就忘了”。建议把项目目录做一个简单的 Git 备份，或者导出笔记目录到自己的文件备份体系里。项目有新版本时，先看 release notes 里有没有破坏性变更，再决定是否更新。
11. 总结与下一步
VelocityNote 这类项目最值得尝试的不是复杂功能，而是“Markdown + 本地 AI”被压到很小时的使用体验。它可以跑在普通办公电脑上，把笔记数据和模型推理都留在本地，同时保住了 Markdown 文件的可迁移性。你最先应该验证的是一条最小链路：新建一篇 Markdown 笔记，写一点表格和代码块，然后调用本地模型做一次文本润色，看看编辑、渲染、推理是否都能顺畅衔接。最容易踩的坑往往集中在模型服务没有提前启动、接口地址配置错误、模型选得太大导致机器卡死这三类，排查时优先从模型运行时日志入手。
后续可以扩展的方向包括：把本地 AI 接口接入更多编辑器，比如 VS Code 插件、Obsidian 插件；在批量任务中加入更完整的失败重试和结果对比；将笔记目录纳入 Git 管理，让历史版本可控；如果需要更好的生成效果，再逐步引入更大参数的量化模型并对比资源占用。先跑通最小配置，再按需升级，这套思路至少不会让机器在浪费时间的同时把热情也一起耗尽。
