Semantica Tutorial 2026：从零部署 Agent Memory

症状：一上来安装全部依赖，结果不知道是 Python、向量库、图数据库还是 LLM 配置出了问题。
最快解法：先用最小后端跑通“安装 → 健康检查 → 写入 → 查询 → 重启验证”，确认 Agent Memory 能工作后，再逐层接入外部组件。

这篇教程适合第一次安装 Semantica 的 Python 开发者、希望把对话或文档转换成 Agent Memory 的原型团队，以及需要建立可重复部署步骤的平台工程师。你不需要一开始就搭建完整企业 Knowledge Graph；先证明一条数据能写入、能查询、能在重启后恢复，才是更稳妥的起点。

第一个可运行目标

先把验收范围缩小到一组能够人工核对的样例：

  • 实体：Alice、Acme Corp
  • 关系：Alice works_for Acme Corp
  • 记忆：Alice 批准了 Acme 的续约
  • 查询：谁批准了 Acme 的续约？
  • 持久化：关闭进程后重新加载，仍能查到这条记录

这样做的价值在于，你可以把“解析失败”“实体没有合并”“查询没有命中”和“数据根本没有保存”分开判断，而不是面对一张看起来正常、实际无法验收的复杂图谱。

官方 Quickstart 将 Semantica 的基本链路拆成采集、解析、实体与关系抽取、构建 Knowledge Graph、可视化和导出；其中 LLM API Key 不是模式抽取的前置条件，首次验证可以先不接模型。官方 Quickstart：安装与首个 Knowledge Graph

建议你在项目目录中先建立以下文件：

semantica-demo/
├── .venv/
├── data/
│   └── sample.txt
├── logs/
├── smoke_test.py
└── requirements.txt

sample.txt 可以先写成：

Alice works for Acme Corp.
Alice approved the Acme renewal.

不要在第一次运行时混入 PDF、网页抓取、OCR、远程向量库和企业图数据库。每增加一层输入复杂度，失败位置就会变得更难定位。

安装环境与命令入口

独立 Python 环境

在 macOS 或 Linux 终端中执行：

mkdir semantica-demo
cd semantica-demo

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install semantica

Windows PowerShell 可使用：

python -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install semantica

官方安装页同时提供核心安装、全部扩展和源码安装方式；首次验证建议使用核心包，而不是直接执行 pip install "semantica[all]"。官方安装说明 PyPI 项目页

版本、导入与 CLI 检查

先确认包能被当前解释器找到：

python -c "import semantica; print(semantica.__version__)"

再检查命令入口：

semantica --help
semantica doctor

semantica doctor 和 semantica --help 是官方仓库 README 当前列出的检查入口；如果你的环境提示“command not found”，先不要修改业务代码，优先确认虚拟环境是否激活，以及 python 和 pip 是否指向同一个环境。官方 GitHub README：CLI 与 doctor

检查项 通过标准 未通过时先查什么
Python 解释器 python 能运行，且不是系统中另一套解释器 which python 或 where python
包导入 能打印 semantica.__version__ 当前虚拟环境是否激活
CLI semantica --help 返回命令帮助 python -m pip show semantica
健康检查 semantica doctor 能完成检查 可选依赖、配置文件和权限
项目写入 logs/ 与状态目录可创建 当前目录权限、磁盘空间

安装失败时的依赖排查

按这个顺序排查，效率通常高于盲目反复安装：

  1. 执行 python --version，确认运行命令使用的解释器。
  2. 执行 python -m pip --version，确认 pip 与解释器属于同一环境。
  3. 执行 python -m pip show semantica，确认实际安装位置。
  4. 把完整错误日志保存到 logs/install-error.txt，不要只复制最后一行。
  5. 暂时移除 [all]、GPU、图数据库和 LLM 扩展，先验证核心包。
  6. 对照官方 API 与模块文档，重新核对模块路径和类名。

⚠️ 不要根据旧博客直接替换包名或导入路径。任务书给出的事实边界要求以官方仓库、官方文档和 PyPI 当前信息为准；历史示例即使能被搜索到，也不代表对应接口仍然有效。

第一批实体与关系

如果你的目标是先验证 Knowledge Graph，而不是先验证文档解析，可以直接使用官方 Quickstart 中的结构化实体与关系格式：

# smoke_test.py
from semantica.kg import GraphBuilder

entities = [
    {"id": "alice", "type": "Person", "name": "Alice"},
    {"id": "acme_corp", "type": "Organization", "name": "Acme Corp"},
]

relationships = [
    {
        "source": "alice",
        "target": "acme_corp",
        "type": "works_for",
    }
]

builder = GraphBuilder(merge_entities=True)
graph = builder.build({
    "entities": entities,
    "relationships": relationships,
})

print("entities:", len(graph["entities"]))
print("relationships:", len(graph["relationships"]))
print(graph)

运行：

python smoke_test.py | tee logs/graph-build.txt

官方 Quickstart 使用 GraphBuilder(merge_entities=True) 合并实体，并通过节点与边数量检查图谱结果。这里的重点不是让图谱看起来复杂，而是保留输入样例、构建代码和输出日志，使你可以逐项对照结果。

如果你要测试 Agent Memory，可以再建立一个独立脚本，不要和图谱构建脚本混在一起：

# memory_test.py
from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

context = AgentContext(
    vector_store=VectorStore(backend="inmemory"),
    knowledge_graph=ContextGraph(),
)

memory_id = context.store(
    "Alice approved the Acme renewal.",
    metadata={"source": "sample.txt"},
)

results = context.retrieve(
    "Who approved the Acme renewal?",
    max_results=5,
)

print("memory_id:", memory_id)
for item in results:
    print(item)

官方 Context 文档把 AgentContext 作为记忆、图关系和决策记录的统一入口，并说明 inmemory 适合零依赖的本地开发。首次测试使用它，可以把向量数据库连接错误从问题列表中暂时移除。官方 Context Module 文档

查询验收与来源核对

第一次查询不要只看“返回了结果”。你至少要核对以下三层：

  • 内容层：结果是否包含 Alice 和 Acme，而不是只返回相似但无关的文本。
  • 关系层：Alice 与 Acme 是否通过预期关系连接，而不是两个孤立节点。
  • 来源层：结果是否保留 sample.txt 或你写入时提供的来源元数据。

如果你从文档开始构建图谱，可以采用官方示例中的最小管线：

from semantica.ingest import FileIngestor
from semantica.parse import DocumentParser
from semantica.semantic_extract import NERExtractor, RelationExtractor
from semantica.kg import GraphBuilder

sources = FileIngestor().ingest("data/sample.txt")
parsed = DocumentParser().parse(sources[0])

ner = NERExtractor(method="pattern")
entities = ner.extract(parsed)

relation_extractor = RelationExtractor(method="rule")
relationships = relation_extractor.extract(
    parsed,
    entities=entities,
)

graph = GraphBuilder(merge_entities=True).build({
    "entities": entities,
    "relationships": relationships,
})

print(graph)

模式抽取适合第一轮验收，因为它不需要 LLM API Key；等你确认文件读取、文本解析、实体抽取和关系构建都正常后，再替换成 LLM 方法。官方文档明确区分了 pattern、rule 和 LLM 驱动的抽取路径。官方实体与关系抽取示例

第一个知识图谱的创建方式

最稳的做法不是直接导入企业文档，而是先用两个人工确认的实体、一个关系和一个可复现查询完成闭环。之后再把 FileIngestor 接到真实目录，并将每次抽取出的实体、关系和来源写入日志；如果结果变化，你才能判断是文档变化、抽取方式变化，还是实体合并策略变化。

重启、保存与重复写入

这里需要区分两种状态：

  1. ContextGraph() 和 inmemory 向量存储本身属于当前进程中的运行状态。
  2. 通过 context.save()、context.load()，或使用持久化图后端，才可以验证跨进程恢复。

官方 Context 文档给出了保存与恢复完整状态的示例：

from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

context = AgentContext(
    vector_store=VectorStore(backend="inmemory"),
    knowledge_graph=ContextGraph(),
)

context.store(
    "Alice approved the Acme renewal.",
    metadata={"source": "sample.txt"},
)

context.save("agent_state/")
print("saved")

然后使用另一个进程或脚本恢复：

from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

restored = AgentContext(
    vector_store=VectorStore(backend="inmemory"),
    knowledge_graph=ContextGraph(),
)

restored.load("agent_state/")

results = restored.retrieve(
    "Who approved the Acme renewal?",
    max_results=5,
)

print(results)

官方示例使用同样的 save() 与 load() 流程验证状态恢复。官方 Persist & Restore 示例

重启后的数据恢复边界

如果你只把数据放在内存对象中，不能把“进程重启后仍然存在”当成默认保证；你必须执行保存与加载，或者把图谱写入外部持久化后端。验收时至少做一次：写入 → 保存 → 停止进程 → 新建对象 → 加载 → 查询，并把查询输出保存到日志。

重复写入同一份数据时，不要预设一定会覆盖或一定会去重。merge_entities=True 解决的是实体合并场景，不等于所有业务记录都具备幂等语义。你应该分别观察：

  • 相同实体再次导入后，节点数量是否变化；
  • 相同关系再次导入后，边数量是否变化；
  • 内容不同但实体名称相同的记录是否被错误合并；
  • 来源和时间字段是否仍然可追溯。

外部图数据库接入

当本地最小流程稳定后，再接入外部图数据库。官方 Quickstart 展示了 Neo4jStore 与 GraphBuilder 的组合方式：

from semantica.graph_store import Neo4jStore
from semantica.kg import GraphBuilder

store = Neo4jStore(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
)

builder = GraphBuilder(
    merge_entities=True,
    graph_store=store,
)

graph = builder.build({
    "entities": entities,
    "relationships": relationships,
})

这个阶段的验收目标是确认数据确实进入外部后端，并且停止 Python 进程后仍可从图数据库读取，而不是只看到本地对象打印出了结果。官方文档还列出 FalkorDB、Apache AGE 和 AWS Neptune 等图存储方向，但具体连接参数必须以对应模块的当前文档为准。官方持久化图存储示例

接入外部图数据库前，先记录：

  • 连接地址和认证方式；
  • 数据库名称或图空间；
  • 当前使用的实体与关系字段；
  • 回滚方式；
  • 一条独立的读查询和一条独立的写查询。

经验：外部后端最容易制造“假成功”。构建代码没有抛异常，不代表数据已经按你预期落盘；必须在 Python 进程外再执行一次查询。

第一周扩展边界

LLM、向量存储、外部图数据库、REST 和 MCP 都可以加入，但不要在同一次变更中全部启用。Semantica 官方仓库将它定位为可位于 LLM、向量存储和 Agent Framework 下方的基础层，图构建、推理和来源记录并不要求必须使用 LLM。官方项目架构说明

建议按以下时间线推进：

  • 第 1 次变更：只加入文档输入，保留结构化样例作为回归测试。
  • 第 2 次变更：加入向量存储，验证语义检索结果与原始文本一致。
  • 第 3 次变更：加入外部图数据库，验证跨进程读取。
  • 第 4 次变更：加入 LLM 抽取，比较模式抽取与模型抽取的实体、关系差异。
  • 第 5 次变更：加入 MCP 或 REST，验证接口层返回的内容与 Python API 一致。

你可以把下面的清单复制到项目 Issue 中，逐项勾选：

  • [ ] 已创建独立虚拟环境，并记录 Python 与 Semantica 版本。
  • [ ] python -c "import semantica" 执行成功。
  • [ ] semantica --help 和 semantica doctor 已运行并保存输出。
  • [ ] 已用最小样例写入实体、关系或一条 Agent Memory。
  • [ ] 已执行精确查询，并与原始输入逐条核对。
  • [ ] 已保存构建日志、查询日志和输入样例。
  • [ ] 已执行 save() 与 load()，确认重启后仍能查询。
  • [ ] 已重复导入同一数据，并记录去重、冲突或覆盖行为。
  • [ ] 每增加一个外部组件，都有独立回滚点和验证脚本。
  • [ ] 只有在核心流程稳定后，才开始接入生产级图数据库或 LLM。

适合你的运行环境

如果你只是在本机试验，独立虚拟环境通常足够；但当你需要比较核心版、完整依赖版、不同 Python 版本，或者反复测试“安装—重启—恢复”流程时，本机环境会逐渐积累缓存、残留服务和无法复现的配置。

这时可以考虑使用 Macstripe 的可重置云端 Mac：为每次验证保留干净镜像，把安装日志、状态目录和测试脚本作为完整工件保存，再分别验证最小安装与扩展安装。你可以先阅读 Macstripe 帮助中心 了解远程环境使用方式，再根据项目需要查看 Macstripe 配置订单说明。

不过，租赁并不适合所有场景。长期稳定运行、需要固定物理接口、需要自行维护本地硬件的团队，直接购买设备可能更合适；如果你的目标是临时验证 Semantica、比较依赖组合，或给团队准备一台可以随时重置的干净环境，云端 Mac 通常比污染个人开发机更容易控制变量。

当你把“安装—健康检查—写入—查询—重启验证”跑通后，再扩展外部图数据库、向量库、LLM 和 MCP，排障范围会明显更小；这正是第一次部署 Agent Memory 时，比一次性安装全部组件更可靠的路径。

延伸阅读