1. 引言
aiddl-common 是 AIDDL（Artificial Intelligence Domain Definition Language）生态中的核心基础包，为 AI 建模、知识表示与推理提供了一套统一的数据结构与工具函数。它既是 AIDDL 语言在 Python 中的参考实现基础，也是构建复杂智能系统的通用底层库。本文将从功能、安装、语法、参数、实际案例和常见错误六个维度，系统介绍 aiddl-common 包的使用方法。
2. aiddl-common 包功能概述
aiddl-common 提供以下核心能力：
- 统一数据模型：提供 Term、Collection、Tuple、List、Set、Map、Reference 等基础数据结构，用于统一表示知识、状态和问题。
- 解析与序列化：支持 AIDDL 文本格式的解析（Parser）与输出（Printer），方便数据交换与持久化。
- 函数与运算：内置常用函数库，包括算术、逻辑、集合运算、字符串处理等。
- 推理基础设施：提供统一的函数调用接口（Function）、模块加载机制（Module）与运行时环境（Runtime），为上层推理引擎提供支撑。
- 工具函数：包含类型转换、比较、哈希、错误处理等通用工具，降低开发成本。
3. 安装方法
aiddl-common 可以通过 pip 直接安装，推荐使用虚拟环境隔离依赖。
pip install aiddl-common如果需要安装最新开发版本，可以从 GitHub 仓库直接安装：
pip install git+https://github.com/aiddl/aiddl-common.git安装完成后，可以通过以下命令验证是否安装成功：
import aiddl_common print(aiddl_common.__version__)4. 核心语法与数据结构
4.1 Term 与基本类型
在 aiddl-common 中，所有数据都以 Term 为基类。常见子类型包括：
- FunRef：函数引用，形如
f(x)。 - Num：数值类型，支持整数与浮点数。
- SymRef：符号引用，用于表示名称、标识符。
- String：字符串类型。
- Bool：布尔类型。
4.2 集合类型
aiddl-common 提供四种主要集合类型：
- Collection：抽象基类，表示一组 Term 的集合。
- Tuple：有序、可重复的序列，类似 Python 的 tuple。
- List：有序、可重复、可变的序列，类似 Python 的 list。
- Set：无序、不可重复的集合，类似 Python 的 set。
- Map：键值对映射，类似 Python 的 dict。
4.3 创建与访问示例
from aiddl_common.term import Tuple, List, Set, Map, SymRef, Num, String 创建 Tuple t = Tuple([Num(1), Num(2), Num(3)]) 创建 List l = List([SymRef("a"), SymRef("b")]) 创建 Set s = Set([Num(1), Num(2), Num(2)]) # 重复元素自动去重 创建 Map m = Map() m.put(SymRef("key"), String("value")) 访问元素 print(t.get(0)) # 输出 1 print(l.get(1)) # 输出 b print(m.get(SymRef("key"))) # 输出 value5. 常用参数与配置
aiddl-common 的许多功能通过参数进行配置，以下列出常用参数：
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| recursive | bool | False | 是否递归处理嵌套集合 |
| include_meta | bool | False | 是否包含元数据信息 |
| sort | bool | False | 是否对集合元素排序 |
| unique | bool | True | Set 是否去重 |
| module_name | str | None | 模块名称，用于模块加载 |
| entry_point | str | None | 模块入口函数名 |
6. 实际应用案例
6.1 案例一：知识表示与存储
使用 Map 和 Tuple 构建简单的知识库，表示实体关系。
from aiddl_common.term import Map, Tuple, SymRef, String knowledge = Map() knowledge.put(SymRef("person:alice"), Tuple([String("Alice"), Num(30)])) knowledge.put(SymRef("person:bob"), Tuple([String("Bob"), Num(25)])) 查询 alice_info = knowledge.get(SymRef("person:alice")) print(alice_info) # 输出 ("Alice", 30)6.2 案例二：集合运算与去重
from aiddl_common.term import Set, Num s1 = Set([Num(1), Num(2), Num(3)]) s2 = Set([Num(3), Num(4), Num(5)]) 并集 union = s1.union(s2) print(union) # 输出 {1, 2, 3, 4, 5} 交集 intersection = s1.intersection(s2) print(intersection) # 输出 {3}6.3 案例三：函数调用与求值
from aiddl_common.runtime import Runtime from aiddl_common.term import FunRef, Num runtime = Runtime() result = runtime.eval(FunRef(SymRef("add"), [Num(2), Num(3)])) print(result) # 输出 56.4 案例四：AIDDL 文本解析
from aiddl_common.parser import Parser parser = Parser() term = parser.parse("(tuple 1 2 3)") print(term) # 输出 (1, 2, 3)6.5 案例五：序列化与持久化
from aiddl_common.printer import Printer from aiddl_common.term import Tuple, Num t = Tuple([Num(1), Num(2), Num(3)]) printer = Printer() text = printer.print(t) print(text) # 输出 (tuple 1 2 3)6.6 案例六：自定义函数模块
from aiddl_common.function import Function from aiddl_common.term import Num, FunRef, SymRef class Double(Function): def call(self, args): return Num(args.get(0).value * 2) runtime = Runtime() runtime.register(SymRef("double"), Double()) result = runtime.eval(FunRef(SymRef("double"), [Num(4)])) print(result) # 输出 86.7 案例七：递归遍历嵌套结构
from aiddl_common.term import Tuple, Num nested = Tuple([Num(1), Tuple([Num(2), Num(3)]), Num(4)]) def flatten(term): result = [] if isinstance(term, Tuple): for item in term: result.extend(flatten(item)) else: result.append(term) return result print(flatten(nested)) # 输出 [1, 2, 3, 4]6.8 案例八：Map 的键值操作与嵌套
from aiddl_common.term import Map, SymRef, String, Tuple config = Map() inner = Map() inner.put(SymRef("host"), String("localhost")) inner.put(SymRef("port"), Num(8080)) config.put(SymRef("server"), inner) server = config.get(SymRef("server")) print(server.get(SymRef("host"))) # 输出 localhost6.9 案例九：与 Python 原生类型互转
from aiddl_common.term import Tuple, List, Set, Map, SymRef, Num, String Term 转 Python t = Tuple([Num(1), String("a")]) py_list = [item.value for item in t] print(py_list) # 输出 [1, "a"] Python 转 Term py_dict = {"x": 1, "y": 2} m = Map() for k, v in py_dict.items(): m.put(SymRef(k), Num(v)) print(m) # 输出 {x: 1, y: 2}7. 常见错误与使用注意事项
7.1 常见错误
| 错误类型 | 原因 | 解决方案 |
|---|---|---|
| TypeError: unsupported operand type | 直接对 Term 对象执行 Python 原生运算 | 使用.value获取原始值后再运算 |
| KeyError | Map 中查找不存在的键 | 先使用contains判断键是否存在 |
| ParserError | AIDDL 文本格式错误 | 检查括号匹配、符号拼写和空格 |
| ModuleNotFoundError | 模块未注册或名称错误 | 确认模块名与注册名一致 |
| IndexError | 访问 Tuple/List 越界 | 先获取长度再访问 |
7.2 使用注意事项
- 不可变性：Tuple 和 Set 是不可变类型，修改需创建新对象；List 和 Map 是可变类型。
- 类型一致性：Set 中元素必须可哈希，Map 的键必须是可哈希的 Term 类型。
- 递归深度：处理深层嵌套结构时注意 Python 递归限制，必要时改用迭代方式。
- 性能考量：大量元素时优先使用 List 而非 Tuple，避免不必要的复制。
- 版本兼容：不同版本间 API 可能有差异，升级前查阅 changelog。
- 线程安全：Runtime 和 Map 非线程安全，多线程场景需自行加锁。
8. 总结
aiddl-common 作为 AIDDL 生态的基础包，提供了统一、灵活的数据结构和丰富的工具函数，适用于知识表示、推理、数据交换等多种场景。通过本文的 9 个案例，读者可以快速掌握其核心用法。在实际项目中，建议结合官方文档和源码，深入理解 Term 体系的扩展机制，以充分发挥 aiddl-common 的潜力。
《AI提示工程必知必会》为读者提供了丰富的AI提示工程知识与实战技能，主要包括各类提示词的应用，如问答式、指令式、状态类、建议式、安全类和感谢类提示词，以及如何通过实战演练掌握提示词的使用技巧；使用提示词进行文本摘要、改写重述、语法纠错、机器翻译等语言处理任务，以及在数据挖掘、程序开发等领域的应用；AI在绘画创作上的应用，百度文心一言和阿里通义大模型这两大智能平台的特性与功能，以及市场调研中提示词的实战应用。通过阅读《AI提示工程必知必会》，读者可掌握如何有效利用AI提示工程提升工作效率，创新工作流程，并在职场中脱颖而出。
