Hotdry.
归档
ai-systems

构建基于LLM的银行交易分类代理：Tally工程实现详解

深入解析Tally项目的工程架构，涵盖多格式交易数据解析、语义类别映射策略与规则引擎集成，提供可落地的LLM代理实现方案。

构建基于 LLM 的银行交易分类代理：Tally 工程实现详解

银行交易分类是个人财务管理与企业财务分析的基础需求，但传统方法面临两大核心挑战：交易描述难以理解（如 "WHOLEFDS MKT 10847 SEATTLE WA"）和分类粒度过于宽泛（如将所有购物归为 "购物" 类别）。Tally 项目通过结合大型语言模型（LLM）与本地规则引擎，提供了一种创新的解决方案。本文将深入解析 Tally 的工程实现，为开发者构建类似系统提供可落地的技术参考。

一、Tally 架构概览：本地优先的 AI 协作模式

Tally 采用 "本地优先" 的设计哲学，所有数据处理都在用户设备上完成，无需依赖云服务或数据库。这种设计带来了三个核心优势：数据隐私保护、离线可用性和零运营成本。

1.1 核心组件架构

Tally 的系统架构包含四个关键组件：

  1. 数据解析层：支持多种银行交易数据格式，包括 CSV、JSON 和特定银行的导出格式。解析器采用自适应策略，能够识别不同银行的字段命名约定。

  2. 规则引擎：基于文本文件的规则系统，使用简单的声明式语法。规则存储在merchants.rules文件中，每条规则包含匹配模式和分类结果。

  3. AI 协作接口：通过标准输入输出与 AI 助手（如 Claude Code、GitHub Copilot）通信，提供上下文感知的交互体验。

  4. 报告生成器：将分类结果转换为 HTML 报告，包含支出分析、类别分布和时间趋势可视化。

1.2 工作流程设计

Tally 的工作流程经过精心设计，最大化 AI 助手的效用：

# 1. 初始化项目
tally init ./my-budget

# 2. 查看工作流指导
tally workflow

# 3. 与AI助手协作分类
# AI助手会分析未分类交易并生成规则

# 4. 生成报告
tally run

这个流程的关键在于tally workflow命令，它为 AI 助手提供上下文信息，包括未分类交易的样本、现有规则的结构和分类目标。

二、多格式交易数据解析策略

银行交易数据的多样性是工程实现的首要挑战。不同银行、不同国家甚至同一银行的不同账户类型都可能使用不同的数据格式。

2.1 自适应解析算法

Tally 采用基于启发式的自适应解析算法，包含以下步骤：

  1. 格式检测：通过分析文件扩展名、分隔符和首行内容识别数据格式。

  2. 字段映射：建立通用字段模型（日期、描述、金额、类别）与源字段的映射关系。

  3. 数据清洗：处理常见的格式问题，如日期格式不一致、金额包含货币符号、描述中的多余空格。

  4. 编码处理：自动检测并转换字符编码，支持 UTF-8、Latin-1 等常见编码。

2.2 CSV 格式字符串配置

Tally 支持灵活的 CSV 格式配置，通过settings.yaml文件定义：

csv_format:
  date_column: "Transaction Date"
  description_column: "Description"
  amount_column: "Amount"
  date_format: "%Y-%m-%d"
  delimiter: ","
  has_header: true
  skip_rows: 0

这种配置方式允许用户精确控制数据解析过程，适应各种银行导出格式。

三、语义类别映射与规则引擎设计

语义类别映射是 Tally 的核心功能，它需要将模糊的交易描述映射到具体的消费类别。

3.1 规则语法设计

Tally 的规则语法简洁而强大，支持多种匹配模式：

# 精确匹配
"AMZN MKTP US*2K7X9" -> "Shopping > Amazon"

# 部分匹配（包含）
contains "STARBUCKS" -> "Food & Drink > Coffee"

# 正则表达式匹配
regex "Uber.*Trip" -> "Transportation > Ride Share"

# 条件规则
"COSTCO" if contains "GAS" -> "Transportation > Fuel"
"COSTCO" otherwise -> "Groceries"

# 优先级规则
"SQ *" -> "Food & Drink"  # Square支付
"SQ *JOES COFFEE" -> "Food & Drink > Coffee"  # 更具体的规则优先

规则引擎采用优先级匹配策略，更具体的规则优先于通用规则。这种设计允许用户逐步细化分类逻辑。

3.2 AI 助手集成策略

Tally 与 AI 助手的集成基于上下文提示工程。当用户运行tally workflow时，系统会生成包含以下信息的提示：

  1. 未分类交易样本：显示 5-10 个代表性的未分类交易
  2. 现有规则摘要：展示当前规则文件的结构和覆盖范围
  3. 分类目标：说明用户希望实现的分类粒度
  4. 规则编写指南：提供规则语法的简要说明

AI 助手基于这些信息分析交易模式，提出分类建议，并生成相应的规则。用户只需审核和确认，大大减少了手动分类的工作量。

四、工程实现的关键参数与配置

4.1 性能优化参数

对于大规模交易数据处理，Tally 提供了以下性能调优选项：

performance:
  batch_size: 1000  # 每次处理的交易数量
  cache_enabled: true  # 启用规则缓存
  cache_ttl: 3600  # 缓存有效期（秒）
  parallel_processing: true  # 启用并行处理
  max_workers: 4  # 最大工作线程数

4.2 分类准确性监控

为确保分类质量，Tally 内置了准确性监控机制：

  1. 规则冲突检测：识别相互冲突的规则定义
  2. 覆盖度分析：统计规则覆盖的交易比例
  3. 模糊匹配警告：标记可能产生歧义的匹配模式
  4. 分类一致性检查：确保相似交易获得一致分类

4.3 错误处理与恢复

Tally 实现了健壮的错误处理策略：

  • 解析错误：记录错误但继续处理其他交易
  • 规则语法错误：提供详细的错误位置和修复建议
  • 数据完整性检查：验证必填字段和数据类型
  • 回滚机制：支持规则文件的版本控制和恢复

五、扩展与集成方案

5.1 API 接口设计

虽然 Tally 主要面向命令行使用，但可以扩展为微服务架构：

from tally.core import TallyEngine

class TallyAPI:
    def __init__(self):
        self.engine = TallyEngine()
        
    def classify_transactions(self, transactions, rules):
        """批量分类交易"""
        return self.engine.classify(transactions, rules)
    
    def generate_rules(self, transactions, categories):
        """基于交易数据生成分类规则"""
        return self.engine.suggest_rules(transactions, categories)
    
    def validate_rules(self, rules):
        """验证规则语法和逻辑"""
        return self.engine.validate(rules)

5.2 与现有财务系统集成

Tally 可以与多种财务系统集成：

  1. 会计软件集成：通过插件将分类结果导入 QuickBooks、Xero 等系统
  2. 预算工具同步：与 YNAB、Mint 等预算工具共享分类数据
  3. 自定义报告生成：基于分类结果生成税务报告、支出分析等
  4. 实时分类服务：构建实时交易分类微服务

5.3 机器学习增强

虽然 Tally 主要依赖规则引擎，但可以集成机器学习模型提升分类能力：

  1. 嵌入向量相似性：使用交易描述的嵌入向量进行相似性匹配
  2. 分类模型集成：训练专门的交易分类模型作为后备方案
  3. 主动学习循环：基于用户反馈持续优化分类规则
  4. 异常检测：识别不符合现有模式的交易

六、实施建议与最佳实践

6.1 分类体系设计

设计有效的分类体系需要考虑以下因素：

  1. 粒度平衡：避免过于细化（难以维护）或过于宽泛（缺乏洞察）
  2. 层次结构：使用层级分类（如 "Food & Drink > Restaurant > Fast Food"）
  3. 业务相关性：根据实际业务需求设计分类
  4. 扩展性：预留空间应对新的消费模式

6.2 规则管理策略

有效的规则管理是长期成功的关键：

  1. 版本控制：将规则文件纳入 Git 版本控制
  2. 定期审查：每月审查和优化规则
  3. 测试套件：创建测试交易验证规则准确性
  4. 文档化：为复杂规则添加注释说明

6.3 性能监控指标

监控以下指标确保系统健康运行：

  • 分类准确率：定期抽样验证分类准确性
  • 处理速度：监控交易处理时间
  • 规则覆盖率：跟踪未分类交易比例
  • 用户满意度：收集用户反馈持续改进

七、局限性与未来发展方向

7.1 当前局限性

Tally 的当前实现存在以下局限性：

  1. 依赖 AI 助手质量：分类准确性受限于 AI 助手的能力
  2. 手动数据导入：需要用户手动导出银行交易数据
  3. 规则维护成本：随着规则数量增加，维护复杂度上升
  4. 多语言支持有限：主要针对英语交易描述优化

7.2 技术演进方向

未来的技术演进可能包括：

  1. 自动数据同步：通过 Open Banking API 自动获取交易数据
  2. 多模型协作：结合多个 LLM 提升分类准确性
  3. 联邦学习：在保护隐私的前提下共享分类知识
  4. 实时分类引擎：支持流式交易数据的实时分类

八、结论

Tally 项目展示了 LLM 与规则引擎结合在银行交易分类领域的强大潜力。通过本地优先的设计、简洁的规则语法和智能的 AI 协作接口，Tally 为用户提供了既强大又易于使用的分类工具。

对于开发者而言，Tally 的工程实现提供了宝贵的参考：自适应数据解析、声明式规则引擎、上下文感知的 AI 交互。这些模式可以应用于其他需要结合规则与 AI 的领域，如文档分类、日志分析和内容审核。

随着 LLM 技术的不断成熟和 Open Banking 生态的发展，基于 AI 的交易分类系统将在个人财务管理、企业财务分析和金融科技应用中发挥越来越重要的作用。Tally 的开源实现为这一领域的发展奠定了坚实的技术基础。

资料来源：

  1. Tally 官方文档：https://tallyai.money/
  2. OpenAI Cookbook 多类别交易分类示例
  3. 弱监督银行交易分类研究论文（arXiv:2305.18430）
查看归档