SymbolicAI：大语言模型的神经符号视角

---

什么是 SymbolicAI？

SymbolicAI 是一个神经符号框架，它将经典的 Python 编程与大语言模型的可微、可编程特性相结合，以一种在 Python 中自然流畅的方式实现。该框架旨在不阻碍你的任何目标，凭借其模块化设计，可以轻松扩展和定制以满足你的需求。你可以很轻松地编写自己的引擎，本地部署你选择的引擎，或者与诸如网络搜索或图像生成之类的工具进行集成。为了使本 README 更加简洁，我们将介绍定义 SymbolicAI 的两个关键概念：原语和契约。

❗️注意❗️ 框架名称旨在致敬启发该项目的艾伦·纽厄尔和赫伯特·西蒙的基础性工作。

原语

SymbolicAI 的核心是 Symbol 对象——每个对象都带有一组小巧、可组合的操作，这些操作用起来就像原生的 Python 代码一样。

from symai import Symbol

Symbol 有两种形式：

1. 句法型 – 行为类似于普通的 Python 值（字符串、列表、整数——无论你传入什么）。
2. 语义型 – 连接到神经符号引擎，因此能够理解含义和上下文。

为什么默认是句法型呢？ 因为 Python 的运算符（==、~、& 等）在 symai 中被重载了。如果我们对每一次位移或比较都立即触发引擎，代码就会变得很慢，并且可能产生意想不到的副作用。从句法型开始可以保证安全和高效；只有在需要时才选择语义型。

如何切换到语义视图

1. 创建时

   S = Symbol("Cats are adorable", semantic=True) # 已经是语义型
   print("feline" in S) # => True
   

2. 按需使用 .sem 投影 – 使用对应的 .syn 可以切换回句法型：

   S = Symbol("Cats are adorable") # 默认是句法型
   print("feline" in S.sem) # => True
   print("feline" in S)     # => False
   

3. 调用点语法操作——例如 .map() 或其他语义函数——会自动将符号切换到语义模式：

    S = Symbol(['apple', 'banana', 'cherry', 'cat', 'dog'])
    print(S.map('convert all fruits to vegetables'))
    # => ['carrot', 'broccoli', 'spinach', 'cat', 'dog']
   

由于这些投影只是为同一个底层对象添加了不同的行为层，因此你可以在单个符号上编织复杂的句法和语义操作链。它们就像是你进行语义推理的构建块。目前我们支持广泛的原语；详细信息请参阅文档这里，以下是一些简要内容：

原语/运算符	类别	句法型	语义型	描述
==	比较	✓	✓	测试相等性。句法型：字面匹配。语义型：模糊/概念等价（例如‘Hi’ == ‘Hello’）。
+	算术	✓	✓	句法型：数字/字符串/列表相加。语义型：有意义的组合、融合或概念合并。
&	逻辑/位运算	✓	✓	句法型：位逻辑与。语义型：逻辑合取、推理，例如上下文合并。
symbol[index] = value	迭代	✓	✓	设置元素或切片。
.startswith(prefix)	字符串辅助	✓	✓	检查字符串是否以给定前缀开头（两种模式下均适用）。
.choice(cases, default)	模式匹配		✓	从提供的选项中选择最佳匹配。
.foreach(condition, apply)	执行控制		✓	对每个元素应用操作。
.cluster(**clustering_kwargs?)	数据聚类		✓	在语义层面将数据聚类成组。（使用 sklearn 的 DBSCAN）
.similarity(other, metric?, normalize?)	嵌入		✓	计算嵌入之间的相似度。
...	...	...	...	...

契约

人们常说大语言模型会“幻觉”，但你的代码可承受不起这样的风险。这就是为什么 SymbolicAI 将契约式设计原则引入大语言模型领域。与其仅仅依赖事后测试，契约可以直接将正确性融入你的设计中，所有内容都封装在一个装饰器里，该装饰器将作用于你定义的数据模型和验证约束：

from symai import Expression
from symai.strategy import contract
from symai.models import LLMDataModel # 兼容 Pydantic 的 BaseModel
from pydantic import Field, field_validator

# ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
#  数据模型                                              ▬
#  – 清晰的结构 + 丰富的字段描述增强了        ▬
#    验证、自动提示模板化及补救措施     ▬
# ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
class DataModel(LLMDataModel):
    some_field: some_type = Field(description="非常详细的字段", and_other_supported_options_here="...")

    @field_validator('some_field')
    def validate_some_field(cls, v):
        # 除了预/后处理之外，还可以在此处添加自定义的基本验证逻辑
        valid_opts = ['A', 'B', 'C']
        if v not in valid_opts:
            raise ValueError(f'必须是 {valid_opts} 中的一个，得到的是 "{v}"。')
        return v

# ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
#  经过契约约束的表达式类                          ▬

# ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
@contract(
    # ── 补救措施 ─────────────────────────────────────────── #
    pre_remedy=True,        # 尝试自动修复不良输入
    post_remedy=True,       # 尝试自动修复LLM的不良输出
    accumulate_errors=True, # 将错误历史传递给每次重试
    verbose=True,           # 在终端中清晰地显示进度
    remedy_retry_params=dict(tries=3, delay=0.4, max_delay=4.0,
                             jitter=0.15, backoff=1.8, graceful=False),
)
class Agent(Expression):
    #
    # 高层次行为：
    #  *. `prompt` – LLM 必须执行的 *静态* 描述（必填）
    #  1. `pre`    – 对输入进行健全性检查（可选）
    #  2. `act`    – 改变状态（可选）
    #  3. LLM      – 生成预期答案（由 SymbolicAI 引擎处理）
    #  4. `post`   – 确保答案符合语义规则（可选）
    #  5. `forward` （必填）
    #     • 如果合约成功 → 返回经过类型验证的 LLM 对象
    #     • 否则                  → 温和的回退答案
    # ...

由于我们不想让这个 README 文件因过长的 Python 代码片段而变得臃肿，关于合约的更多信息请参阅 这里 和 这里。

安装

核心功能

要开始使用 SymbolicAI，您可以使用 pip 进行安装：

pip install symbolicai

或者，克隆仓库并使用 uv（≥ 0.9.17）设置 Python 虚拟环境：

git clone git@github.com:ExtensityAI/symbolicai.git
cd symbolicai
uv sync --python x.xx
source ./.venv/bin/activate

现在运行 symconfig 将会使用这个 Python 环境。

可选功能

SymbolicAI 使用多个引擎来处理文本、语音和图像。我们还集成了搜索引擎访问功能，以便从网络上获取信息。要使用所有这些功能，您还需要安装以下依赖项，并将 API 密钥分配给相应的引擎。例如：

pip install "symbolicai[bitsandbytes]"
pip install "symbolicai[hf]"
pip install "symbolicai[lean]"
pip install "symbolicai[llama_cpp]"
pip install "symbolicai[ocr]"
pip install "symbolicai[qdrant]"
pip install "symbolicai[scrape]"
pip install "symbolicai[search]"
pip install "symbolicai[serpapi]"
pip install "symbolicai[services]"
pip install "symbolicai[solver]"
pip install "symbolicai[whisper]"
pip install "symbolicai[wolframalpha]"

或者，一次性安装所有可选依赖项：

pip install "symbolicai[all]"

要按照提供的锁定文件精确安装依赖项：

uv sync --frozen

通过 uv 安装可选扩展：

uv sync --extra all # 所有可选扩展
uv sync --extra scrape # 仅安装 scrape 相关依赖

❗️注意❗️请注意，其中一些可选依赖可能需要额外的安装步骤。此外，部分功能目前仅处于实验性支持阶段，可能无法按预期工作。如果您对某项功能极为重要，请考虑为项目贡献代码或与我们联系。

配置管理

SymbolicAI 现在配备了基于优先级加载的配置管理系统。该系统会按优先级顺序在三个不同位置查找配置：

1. 调试模式（当前工作目录）

   • 优先级最高
   • 仅适用于 symai.config.json
   • 适用于开发和测试

2. 环境特定配置（Python 环境）

   • 优先级第二
   • 位于 {python_env}/.symai/
   • 适合项目特定的设置

3. 全局配置（主目录）

   • 优先级最低
   • 位于 ~/.symai/
   • 所有设置的默认回退

配置文件

系统管理三个主要配置文件：

• symai.config.json: 主 SymbolicAI 配置
• symsh.config.json: Shell 配置
• symserver.config.json: 服务器配置

查看您的配置

在使用 symai 之前，我们建议您使用以下命令检查当前的配置设置。该命令将启动初始包缓存，并初始化 symbolicai 的配置文件。

symconfig

# UserWarning: 未找到环境的配置文件。已在 <full-path>/.symai/symai.config.json 创建了一个新的配置文件。请配置您的环境。

随后您需要编辑 symai.config.json 文件。使用 symai 包时，必须配备神经符号引擎。有关如何使用神经符号引擎的更多信息，请参阅 这里。

此命令将显示：

• 所有配置位置
• 活动配置路径
• 当前设置（敏感数据已被截断）

配置优先级示例

my_project/              # 调试模式（最高优先级）
└── symai.config.json    # 调试模式下仅检查此文件

{python_env}/.symai/     # 环境配置（第二优先级）
├── symai.config.json
├── symsh.config.json
└── symserver.config.json

~/.symai/                # 全局配置（最低优先级）
├── symai.config.json
├── symsh.config.json
└── symserver.config.json

如果某个配置文件存在于多个位置，系统将使用优先级最高的版本。如果环境特定配置缺失或无效，系统将自动回退到主目录中的全局配置。

最佳实践

• 使用全局配置 (~/.symai/) 作为默认设置
• 使用环境特定配置来存储项目相关的设置
• 使用调试模式（当前目录）进行开发和测试
• 运行 symconfig 来检查当前的配置设置

配置文件

您可以在项目路径中创建一个 symai.config.json 文件来指定引擎属性。这将覆盖环境变量。

所有引擎都启用的配置文件示例如下：

{
    "NEUROSYMBOLIC_ENGINE_API_KEY": "<ANTHROPIC_API_KEY>",
    "NEUROSYMBOLIC_ENGINE_MODEL": "claude-sonnet-4-6",
    "SYMBOLIC_ENGINE_API_KEY": "<WOLFRAMALPHA_API_KEY>",
    "SYMBOLIC_ENGINE": "wolframalpha",
    "FORMAL_ENGINE_API_KEY": "<AXIOM_API_KEY>",
    "FORMAL_ENGINE": "axiom",
    "EMBEDDING_ENGINE_API_KEY": "<OPENAI_API_KEY>",
    "EMBEDDING_ENGINE_MODEL": "text-embedding-3-small",
    "SEARCH_ENGINE_API_KEY": "<PARALLEL_API_KEY>",
    "SEARCH_ENGINE_MODEL": "parallel",
    "TEXT_TO_SPEECH_ENGINE_API_KEY": "<OPENAI_API_KEY>",
    "TEXT_TO_SPEECH_ENGINE_MODEL": "tts-1",
    "INDEXING_ENGINE": "qdrant",
    "INDEXING_ENGINE_API_KEY": "<QDRANT_API_KEY>",
    "INDEXING_ENGINE_URL": "http://localhost:6333",
    "DRAWING_ENGINE_API_KEY": "<BFL_API_KEY>",
    "DRAWING_ENGINE_MODEL": "flux-pro-1.1",
    "VISION_ENGINE_MODEL": "openai/clip-vit-base-patch32",
    "OCR_ENGINE_API_KEY": "<OCR_API_KEY>",
    "OCR_ENGINE_MODEL": "mistral-ocr-latest",
    "SPEECH_TO_TEXT_ENGINE_MODEL": "turbo",
}

完成以上步骤后，您应该就可以在项目中开始使用 SymbolicAI 了。

❗️注意❗️ 默认情况下，用户警告是启用的。要禁用它们，请在您的环境变量中导出 SYMAI_WARNINGS=0。

运行测试

以下是一些在本地运行测试的示例：

# 运行所有测试
pytest tests
# 运行强制性测试
pytest -m mandatory

请确保在运行测试之前正确配置好相关设置。您还可以运行带有覆盖率的测试，以查看有多少代码被测试覆盖：

pytest --cov=symbolicai tests

🪜 下一步

现在有一些工具，比如 DeepWiki，提供了比我们所能编写的更好的文档，我们并不想与之竞争；只有在明显错误的地方，我们才会进行修正。请前往 SymbolicAI 的 DeepWiki 页面阅读相关内容。那里有很多有趣的信息。最后，别忘了查看我们的 论文，其中详细介绍了该框架。如果您喜欢观看视频，我们还有一系列教程，您可以在这里找到：SymbolicAI 教程视频。

📜 引用

@article{dinu2024symbolicai,
  title={Symbolicai: A framework for logic-based approaches combining generative models and solvers},
  author={Dinu, Marius-Constantin and Leoveanu-Condrei, Claudiu and Holzleitner, Markus and Zellinger, Werner and Hochreiter, Sepp},
  journal={arXiv preprint arXiv:2402.00854},
  year={2024}
}

📝 许可证

本项目采用 BSD-3-Clause 许可证。

喜欢这个项目吗？

如果您喜欢这个项目，请给它点个赞 ⭐️ 并分享给朋友和同事。为了进一步支持该项目的持续开发，您也可以考虑捐赠。感谢您的支持！

我们也在寻找贡献者或投资者来帮助发展和支持这个项目。如果您感兴趣，请随时与我们联系。

📫 联系方式

如有关于该项目的问题，欢迎通过 电子邮件、我们的 网站 或 Discord 与我们联系：

SymbolicAI 快速上手指南

环境准备

系统要求

• Python 3.8 或更高版本
• 支持 pip 和 uv（推荐）的环境

前置依赖

• 无需额外安装，除非使用可选功能（如搜索、OCR、图像生成等）

安装步骤

核心安装

pip install symbolicai

使用 uv 设置虚拟环境（推荐）

git clone git@github.com:ExtensityAI/symbolicai.git
cd symbolicai
uv sync --python 3.10
source ./.venv/bin/activate

可选功能安装

安装所有可选功能：

pip install "symbolicai[all]"

或按需安装：

pip install "symbolicai[search]"
pip install "symbolicai[ocr]"
pip install "symbolicai[wolframalpha]"

⚠️ 注意：部分可选功能可能需要额外配置或仅实验性支持。

基本使用

创建符号对象

from symai import Symbol

# 创建语法符号
s = Symbol("Cats are adorable")
print("feline" in s)  # => False

# 创建语义符号
s = Symbol("Cats are adorable", semantic=True)
print("feline" in s)  # => True

使用 .sem 切换到语义视图

s = Symbol("Cats are adorable")
print("feline" in s.sem)  # => True

执行语义操作

s = Symbol(['apple', 'banana', 'cherry', 'cat', 'dog'])
print(s.map('convert all fruits to vegetables'))
# 输出: ['carrot', 'broccoli', 'spinach', 'cat', 'dog']

使用 Contracts（设计契约）

from symai import Expression
from symai.strategy import contract
from symai.models import LLMDataModel
from pydantic import Field, field_validator

class DataModel(LLMDataModel):
    some_field: str = Field(description="描述字段")

    @field_validator('some_field')
    def validate_some_field(cls, v):
        if v not in ['A', 'B', 'C']:
            raise ValueError(f'必须是 A、B 或 C，得到的是 "{v}"')
        return v

@contract()
class Agent(Expression):
    def forward(self):
        return self._llm_call()

配置管理

运行以下命令初始化配置：

symconfig

然后编辑 ~/.symai/symai.config.json 文件，确保配置了神经符号引擎。