使用说明

语义集成引擎（SIE）

这 语义集成引擎（SIE） 是一个混合语义向量设计用于集成结构化知识图的检索引擎，符号推理和现代嵌入模型。

SIE可以用作 独立RAG发动机，提供：

高质量的文本到知识检索
用于AI代理的REST和MCP接口
混合符号+向量推理

然而，SIE也是作为
SimpleModeling.org/SmartDox生态系统，在那里它实现了它的充分的潜力。

当与以下内容结合时：

SmartDox （结构化、双语、语义丰富的文档）
SimpleModeling.org知识图谱 （基于RDF/JSON-LD的BoK）

SIE成为 基于知识的人工智能引擎 能够：

理解领域模型和概念结构
用明确的语义语境回答问题
执行尊重本体、类别、引用的检索，文档结构
支持人工智能辅助建模、文档和开发工作流程

简言之： SIE可以独立工作，但它变得更加强大当与SimpleModeling.org的语义知识库集成时。

CNCF边界合同

ExecutionContext由CNCF提供，并由SIE作为只读数据使用。
SIE不得从ExecutionContext构造、变异或推断语义。
CanonicalId是不透明的，仅用于相关性。

🌐 架构概述

┌───────────────────────────────────────────────────────────┐
│                   Semantic Integration Engine (SIE)       │
│                                                           │
│   ┌──────────────┐     ┌────────────────────────────┐    │
│   │  Fuseki RDF  │<----│  init-fuseki (one-shot KG) │    │
│   └──────────────┘     └────────────────────────────┘    │
│          ↑                                                 │
│          │ SPARQL                                          │
│          │                                                 │
│   ┌───────────────┐                                       │
│   │ sie-embedding │----→ vector search                     │
│   └───────────────┘                                       │
│                                                           │
│ REST API: /api                                            │
│ MCP API : ws://host:9050/mcp                              │
└───────────────────────────────────────────────────────────┘

SIE集成了基于符号和嵌入的检索，以生成基于SimpleModeling知识图的上下文感知答案。

本概述侧重于运行时和部署组件。 MCP协议设计、适配器和工具语义分别记录。

🔧 构建与运行（开发）

sbt clean assembly

胖JAR生成于：

dist/semantic-integration-engine.jar

java -jar dist/semantic-integration-engine.jar

环境变量：

FUSEKI_URL –RDF端点（默认值：http://localhost:3030/ds)
SIE_EMBEDDING_URL –嵌入后端
SIESERVER_PORT –REST/MCP服务器端口

🧪 开发启动流程（推荐）

在DEV模式下，SIE被设计为运行 Docker之外 在本地JVM上，外部知识库由Docker提供。

这实现了本地数据的快速迭代、调试和安全重置。

架构（DEV）

Local JVM (sbt dev)
    └─ Semantic Integration Engine (SIE)
         ├─ GraphDB  → Fuseki (Docker)
         └─ VectorDB → sie-embedding / Chroma (Docker)

一步一步

启动外部依赖项（GraphDB/VectorDB）：
```
docker compose -f docker-compose.dev.yml up -d
```
这将开始：
- Apache Jena Fuseki（RDF/知识图）
- sie嵌入（嵌入+Chroma支持的矢量数据库）
在本地启动SIE：
```
sbt dev
```
SIE通过localhost连接到Docker管理的服务。
验证状态：
```
curl http://localhost:9050/status | jq
```
您应该看到：
- 模式=DEV
- graphDb/vectorDb角色和准备状态
- 总体状态=健康|降级|不可用
注：
- healthy ：所有必需的子系统都已准备就绪
- degraded ：系统在能力有限的情况下运行（例如矢量索引初始化）
- unavailable：无法提供语义查询

端点分辨率（DEV）

在DEV模式下，端点解析如下：

默认端点（无需配置）：
- 富塞基→ http://localhost:9030/ds
- 矢量数据库→ http://localhost:8081
- 嵌入→ http://localhost:8081/embed
替代（仅限高级使用）：
- 环境变量：
  - FUSEKI_URL
  - SIE_VECTORDB_ENDPOINT
  - SIE_EMBEDDING_ENDPOINT
- 中的明确定义 application.dev.conf

请参阅评论 application.dev.conf 和 AppConfig.scala 对于完整的DEV解析策略。

🐳 构建Docker镜像（使用现有的Dockerfile）

docker build -t ghcr.io/asami/sie:latest .
docker push ghcr.io/asami/sie:latest

演示环境（可选）

一个完整的演示环境——包括Fuseki、嵌入式后端、自动 RDF加载器和SIE本身——通过以下方式提供：

docker-compose.demo.yml
GHCR托管的图像：
- ghcr.io/asami/init-fuseki:latest
- ghcr.io/asami/sie-embedding:latest
- ghcr.io/asami/sie:latest

该演示旨在：

混合检索管道的评估
在SimpleModeling知识图上探索语义查询
演示MCP工具与ChatGPT的集成
复制SimpleModeling.org文章中的示例

🚀 运行演示

docker compose -f docker-compose.demo.yml up -d

可用端点：

Fuseki用户界面：http://localhost:9030
您的 REST API:http://localhost:9050/api
MCP WebSocket：ws://localhost:9050/MCP

REST查询示例

curl -X POST http://localhost:9050/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain SimpleModelObject."}'

MCP会话示例（wscat）

wscat -c ws://localhost:9050/mcp

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}

重新创建容器以确保图像更新

当你在本地重建Docker镜像（用于演示或生产验证）时， Docker Compose可能会继续使用基于旧映像的现有容器。

为了确保实际使用最新的本地构建的图像，建议显式地重新创建容器。

推荐命令：

docker compose up -d --force-recreate

此命令可确保：

停止并重新创建现有容器
使用最新的本地Docker镜像
前几次运行中没有过期的容器

使用--在以下情况下强制重新创建：

您在本地重建了SIE Docker映像
您更新了MCP设置脚本或模板
您希望可靠地验证演示或生产图像

在验证演示环境时，这种做法特别有用或者在发布之前测试生产图像。

🔀 选择您的MCP客户端

协议边界和交互合同

SIE通过多种方式公开其功能 协议特定端点 同时共享一个内部 互动合同.

/api
用于应用程序和系统集成的REST接口。
/mcp
MCP接口使用 严格的JSON-RPC 2.0，用于AI代理， IDE和基于CLI的MCP客户端。

每个外部协议都通过专用的 协议入口 （输入边界）和 协议适配器 （输出边界），而 SieService 仍然是操作语言的唯一执行者。

这种设计将协议关注点与语义执行清晰地分开并允许REST、MCP和未来的集成（如ChatGPT）发展独立地。

SIE通过分离MCP核心来支持多个MCP客户端来自协议特定适配器（ChatGPT/JSON-RPC）。

执行上下文（计划）

SIE遵循CNCF设计 执行上下文 已建成通过 SieService 当创建一个 操作电话.

ExecutionContext来源于：

隐式包含在请求中的编码执行提示，以及
运行时/环境参数（模式、策略、区域设置、时间等）。

ExecutionContext是 绑定到OperationCall 并隐式访问通过操作实现，保持操作语言本身的纯净。

状态： 设计同意。
实施和布线是有意的搁置目前。

🧰 MCP工具命名约定（SIE）

SIE exposes its MCP tools as a **stable semantic API** shared by both
ChatGPT and VS Code MCP clients.

Tool names are designed to be:
- Semantically meaningful
- Predictable for LLM tool selection
- Stable across versions
- Independent of transport or implementation details

### Naming Rules

- Tool names use **camelCase**
- Structure: `<verb><Object>`
- Verbs represent **intent / operation**
- Objects represent **SIE domain vocabulary**
- Tool names are treated as **stable APIs** (avoid breaking changes)

### Allowed Verbs

| Verb | Meaning |
|------|--------|
| `explain` | Explain a concept, model, or document |
| `query` | Perform conditional or exploratory queries |
| `list` | List available resources |
| `get` | Retrieve a single resource by identifier |
| `resolve` | Resolve references or relationships |
| `analyze` | Perform analysis or evaluation |
| `validate` | Validate structure or constraints |
| `generate` | Generate derived artifacts |

Avoid vague verbs such as `do`, `run`, `execute`, or `process`.

### Standard SIE Objects

| Object | Meaning |
|--------|--------|
| `Concept` | Conceptual entity (LexiDox / CML) |
| `Graph` | Semantic knowledge graph |
| `Document` | Structured document |
| `Passage` | Document fragment |
| `Model` | Domain or system model |
| `Entity` | Domain entity |
| `Vocabulary` | Controlled vocabulary |
| `Ontology` | RDF / OWL structure |

### Example Tool Names

- `explainConcept`
- `queryGraph`
- `listDocuments`
- `getDocument`
- `resolveConcept`
- `analyzeModel`

### Versioning Policy

- Tool names are **not renamed** once published
- Breaking changes require a version suffix:

解释概念2


- Older versions may coexist during migration

### Design Rationale

- Tool names represent **semantic intent**, not implementation
- Transport details (`ws`, `stdio`, `mcp`) are intentionally excluded
- Internal technologies (`rdf`, `sparql`, `vector`, `embedding`) are hidden
- This allows the same tool set to be used consistently from:
  - ChatGPT (WebSocket-based MCP)
  - VS Code (stdio-based MCP)

您可以使用 VS Code 或 ChatGPT 作为MCP客户端。

除了基于MCP的客户端之外，SIE还公开了传统的REST API。这允许您使用SIE 无MCP，使用标准HTTP工具。

选项C：REST API（直接HTTP访问）

REST API可用于：

快速测试 curl 或HTTP客户端
与现有应用程序集成
无需MCP工具即可理解SIE行为

REST端点

http://localhost:9050/api/query

REST查询示例

curl -X POST http://localhost:9050/api/query \
  -H "Content-Type: application/json" \
  -d '{ "query": "Explain SimpleModelObject." }'

REST API和MCP API共享相同的底层语义引擎。 REST接口有意保持简单和无状态。

MCP客户端（基于stdio的CLI）

这 mcp-client 可以作为独立设备使用 基于stdio的CLI.

它接受：

通过STDIN发送MCP JSON-RPC消息
交互式 元命令 从...开始 : 用于客户端控制

这允许开发人员检查和调试MCP初始化和功能而不依赖于VS Code或其他MCP运行时。

VS Code MCP集成现状

在撰写本文时，VS Code不会自动调用中定义的MCP stdio服务器 .vscode/settings.json.

虽然该配置在语法上是正确的， MCP运行时未被激活，以及 initialize / get_manifest 不是由VS代码触发的。

因此，该存储库提供了 基于CLI的工作流 作为一种实用且可重复的替代方案。

MCP客户端元命令

以下元命令受支持 mcp-client:

:help
显示可用的元命令。
:status
显示客户端角色、传输和REST端点。
:initialize
转储合并的MCP初始化响应(initialize.json + mcp.json).
:manifest
转储MCP功能（工具定义）。
:exit, :quit
立即退出客户端。

退出MCP客户端

由于此客户端在stdio模式下运行，信号处理可能会有所不同这取决于执行环境（终端、Docker、Emacs等）。

始终支持并推荐以下元命令：

:exit
:quit

即使在Ctrl-C或EOF下，这些命令也会可靠地终止客户端未正确传播。

为什么选择CLI？

MCP被设计为一种工具连接协议，但它的运行时支持在编辑方面仍在不断发展。

提供CLI允许：

MCP初始化的确定性检查
无编辑器特定行为的调试
可复制的演示和文档

因此，此CLI 不是退路，但这是一个深思熟虑的设计选择。

📄 许可证

软件（代码）

根据 Apache许可证2.0
https://www.apache.org/licenses/LICENSE-2.0

文档（文本、示例、图表）

根据以下许可 CC-BY-SA 4.0
https://creativecommons.org/licenses/by-sa/4.0/

🤝 贡献

欢迎投稿、问题和功能请求。
请在GitHub上打开问题或拉取请求。

使用说明

语义集成引擎（SIE）

CNCF边界合同

🌐 架构概述

🔧 构建与运行（开发）

🧪 开发启动流程（推荐）

架构（DEV）

一步一步

端点分辨率（DEV）

🐳 构建Docker镜像（使用现有的Dockerfile）

演示环境（可选）

🚀 运行演示

REST查询示例

MCP会话示例（wscat）

重新创建容器以确保图像更新

🔀 选择您的MCP客户端

协议边界和交互合同

执行上下文（计划）

🧰 MCP工具命名约定（SIE）

选项C：REST API（直接HTTP访问）

REST端点

REST查询示例

MCP客户端（基于stdio的CLI）

VS Code MCP集成现状

MCP客户端元命令

退出MCP客户端

为什么选择CLI？

📄 许可证

软件（代码）

文档（文本、示例、图表）

🤝 贡献

相关 MCP

知识图谱记忆服务器

AI持久记忆服务器

知识图谱存储服务

百度优选

自主代理操作系统

知识图谱记忆系统