NSAA — Neuro-Symbolic Agent Architecture

版本: 0.3.0 | 接口版本: 1.0 | 日期: 2026-11-03

与 Orchidea Intel 是两个独立子项目：NSAA 为 Python 论文验证骨架，Intel 为 TypeScript 上市企业分析服务，两者无代码依赖，不得互相表述为”产品化形态”。

研究/论文验证定位（骨架，非推理器）

本项目当前为 NSAA 论文验证用骨架实现，尚不具备生产推理能力：

• 无 LLM：未接入任何大语言模型，无真实语义推理能力；
• 随机权重：神经模块权重为随机初始化，未经训练；
• 合成输出：推理与路由输出为合成占位结果，不代表真实模型行为。

因此，本项目不纳入生产镜像主链路，仅用于 NSAA 论文验证。

NSAA（Neuro-Symbolic Agent Architecture，神经符号智能体架构）深度融合类脑脉冲神经网络隐状态动力学与显式符号知识图谱，重新定义智能体系统的核心知识层。

2026-11 能力更新（v0.3.0）

• ESGL 显式符号图层：DynamicKnowledgeGraph（ACID / provenance / 置信度）、Datalog 风格规则引擎（递归推理与一致性检查）、符号驱动工具编排、因果链追溯
• 部署：DKG 快照与 docker-compose 同步更新

架构概览

+------------------+     Action Layer       (工具调用 / 环境交互)
+------------------+
         ↑↓
+------------------+     ESGL — 显式符号图谱层    (长期记忆 & 逻辑 conscience)
| DKG / LRCC / TIAO |      DynamicKnowledgeGraph / LogicRuleEngine / ToolInterface
+------------------+
         ↑↓  NSB — 神经符号双向桥
+------------------+     CDKL — 类脑动态知识层    (工作记忆 & 直觉推理引擎)
| HSWM / SDAR / TIKI |     GatedLinearAttention / AdaptiveSpikingNeuron
+------------------+
         ↑↓
+------------------+     Perception Layer     (文本编码 / 视觉特征 / 传感器)
+------------------+

核心模块

总计: ~8,400 行 Python 代码

快速开始

安装依赖

pip install -r requirements.txt

运行测试

# 运行全部测试
pytest tests/ -v

# 排除慢测试
pytest tests/ -v -m "not slow"

# 运行性能基准
pytest tests/test_e2e.py -v --benchmark-only

使用示例

import torch
from nsaa import (
    GatedLinearAttention, AdaptiveSpikingNeuron,
    DynamicKnowledgeGraph, ESGLComposite,
    create_nsb_bridge,
    AgentSignatureBank, SparsityDrivenAgentRouter
)

# 1. CDKL — 门控线性注意力
gla = GatedLinearAttention(dim=256, num_heads=4)
x = torch.randn(2, 128, 256)  # [B, T, D]
output, state, meta = gla(x, use_chunk=True)
print(f"Output: {output.shape}, Sparsity: {meta['sparsity']:.2%}")

# 2. CDKL — 自适应脉冲神经元
asn = AdaptiveSpikingNeuron(dim=256)
spike, mem, sparsity = asn(x[:, -1, :])  # 取最后一步
print(f"Spike sparsity: {sparsity:.2%}")

# 3. NSB — 神经符号双向桥
nsb = create_nsb_bridge(state_dim=256)
# 符号 → 神经
subgraph = {'nodes': torch.tensor([1, 2, 3]), 'edges': torch.tensor([[1, 2, 0]])}
state_bias = nsb['s2n'](subgraph)
print(f"State bias: {state_bias.shape}")

# 4. SDAR — 脉冲驱动路由
sdar = SparsityDrivenAgentRouter(dim=256, num_agents=5)
final_out, weights, meta = sdar(x[:, -1, :], spike)
print(f"Agent weights: {weights}")

# 5. ESGL — 动态知识图谱 (async)
import asyncio
esgl = DynamicKnowledgeGraph()
updates = [GraphUpdate(op='add_node', subject='Alice', properties={'age': 30})]
result = asyncio.run(esgl.apply_updates(updates))

关键特性

定理保证

性能指标

项目结构

nsaa/
├── __init__.py          # 包导出
├── cdkl.py              # CDKL — 类脑动态知识层
│   ├── GatedLinearAttention
│   ├── AdaptiveSpikingNeuron
│   ├── HiddenStateWorkingMemory
│   └── TrainingInferenceConsistentInternalization
├── esgl.py              # ESGL — 显式符号图谱层
│   ├── GraphUpdate
│   ├── DynamicKnowledgeGraph
│   ├── LogicRuleEngine
│   ├── ToolInterfaceOrchestrator
│   ├── CausalChainTracer
│   └── ESGLComposite
├── nsb.py               # NSB — 神经符号双向桥
│   ├── SymbolicToNeuralEncoder
│   ├── NeuralToSymbolicDecoder
│   ├── BidirectionalConsistencyLoss
│   ├── NeuroSymbolicValidator
│   └── create_nsb_bridge
└── sdar.py              # SDAR — 脉冲稀疏度驱动路由
    ├── AgentConfig
    ├── AgentSignatureBank
    ├── SparsityDrivenAgentRouter
    ├── MultiAgentCoordinator
    ├── RoutingPolicyOptimizer
    └── SDARModule

tests/
├── conftest.py          # pytest 配置
├── test_cdkl.py         # CDKL 单元测试 (55 tests)
├── test_esgl.py         # ESGL 单元测试 (42 tests)
├── test_nsb.py          # NSB 单元测试 (30 tests)
├── test_sdar.py         # SDAR 单元测试 (36 tests)
└── test_e2e.py          # 端到端测试 (21 tests)

接口契约

所有模块遵循统一的 NSAAComponent 协议：

class NSAAComponent(Protocol):
    def forward(self, x: torch.Tensor, **kwargs) 
        -> Tuple[torch.Tensor, Dict[str, Any]]:
        """Returns: (output, state_dict with 'hidden_state', 'spikes', 'metadata')"""
        ...
    
    def get_config(self) -> Dict[str, Any]:
        """Return module configuration for serialization"""
        ...

模块间数据交换格式

# CDKL → NSB
cdkl_output = {
    'hidden_state': torch.Tensor,  # [B, D, D]
    'spikes': torch.Tensor,        # [B, D]
    'metadata': {
        'sparsity': float,
        'num_active_neurons': int,
        'state_delta': float,
        'timestamp': float,
    }
}

# NSB → ESGL
nsb_output = {
    'graph_updates': List[GraphUpdate],
    'concept_activations': Dict[str, float],
    'debug_info': {
        'encoding_time_ms': float,
        'decoding_time_ms': float,
    }
}

技术约束

• PyTorch >= 2.0.0，BF16 支持
• 推理内存：严格 O(d²)，与序列长度无关
• 所有图谱操作：async/await
• 路由决策：< 1ms
• 编码/解码延迟：< 10ms
• 完整 Python type hints

参考文献

1. Vaswani, A., et al. “Attention is all you need.” NeurIPS, 2017.
2. Yao, S., et al. “ReAct: Synergizing reasoning and acting in language models.” ICLR, 2023.
3. Pan, Y., et al. “SpikingBrain: Spiking Brain-inspired Large Models.” arXiv:2509.05276, 2025.
4. Maass, W. “Networks of spiking neurons: the third generation of neural network models.” 1997.
5. Garcez, A. S., et al. “Neural-symbolic computing.” arXiv:1905.06088, 2019.

部署说明

Docker 镜像

deploy/Dockerfile 基于 python:3.11-slim 构建，暴露 8000（REST）与 50051（gRPC）端口，以 uvicorn nsaa.api.rest:app 启动服务，内置健康检查（/health）。

cd orchidea-NSAA
docker build -f deploy/Dockerfile -t orchidea-nsaa .
docker run -p 8000:8000 -p 50051:50051 orchidea-nsaa

Docker Compose（开发环境）

deploy/docker-compose.yml 一键拉起完整服务栈：

docker compose -f deploy/docker-compose.yml up -d

安全提醒：生产环境务必通过环境变量修改 NEO4J_PASSWORD 与 NSAA_API_KEYS，建议使用 Docker secrets 管理敏感信息。

Kubernetes（生产环境）

deploy/helm/orchidea-nsaa/ 提供 Helm Chart（Chart 版本与 appVersion 均为 0.2.0）：

• deployment.yaml / service.yaml：服务编排（HTTP 8000 / gRPC 50051）
• hpa.yaml：水平自动扩缩容（默认关闭，可按 CPU 使用率启用）
• ingress.yaml：外部访问入口
• configmap.yaml / secret.yaml：配置注入（OIDC、缓存、租户配额、Neo4j 连接）
• 内置 Neo4j（neo4j:5-community，10Gi 持久化）与 Prometheus 采集配置

helm install orchidea-nsaa deploy/helm/orchidea-nsaa/

本地运行与测试

pip install -r requirements.txt

# 运行全部测试
pytest tests/ -v

# 启动服务
uvicorn nsaa.api.rest:app --host 0.0.0.0 --port 8000

许可证

MIT，详见仓库根目录 LICENSE 文件。

NSAA 架构基于与 LuxiTech 类脑计算系统的深入技术对话设计，受 SpikingBrain 开源项目启发。