DataFinder 企业语义层演示实战：用自然语言跨 HubSpot、Jira 与 Dynamics 365 查询数据

• AI 应用
• MCP 服务
• AI Agent
• 后端
• 前端

导读

本文以 NLWeb 仓库中 DataFinder 项目的官方演示脚本（DEMO_SCRIPT.md）为主线，完整还原一套 5～7 分钟的端到端演示流程：如何用一句英文问题让 DataFinder 自动完成模板匹配、值映射、语义到 SQL 的编译、跨数据库 JOIN 与 LLM 风险评估。读完本文，你将掌握 DataFinder 的安装运行方式、五组演示命令及其背后的调用链，并能向团队复现"基于支持工单的大额商机风险"这类跨系统分析查询——全程无需手写任何集成代码。

一、演示背景：为什么需要语义层

DataFinder 是一个"企业语义层"（enterprise semantic layer）概念验证项目，核心价值是把散落在多个业务系统中的客户数据统一成一张可查询的语义视图。演示脚本首先点出的痛点非常典型：

• 客户的营销数据在HubSpot（负责市场与早期销售线索）；
• 客户支持工单在Jira（Jira Service Management 风格的工单系统）；
• 客户销售商机在Dynamics 365 Sales（负责后期销售与订单）。

每个系统都有自己的 schema：字段名不同、ID 体系不同、状态枚举不同。传统做法是写自定义集成代码去打通这些系统；而 DataFinder 用一套基于 Schema.org 的语义层（语义本体 + TMCF/JSON-LD 映射 + 自然语言翻译器）提供统一视图，让业务问题直接变成跨系统查询。

需要说明：演示脚本中展示映射文件的命令为cat mappings/hubspot_tmcf.yaml，而当前仓库实际落地的是 JSON-LD 格式的映射文件（hubspot.jsonld、jira.jsonld、dynamics365.jsonld），下文均以仓库实际情况为准。

二、演示环境准备（Pre-recording）

按脚本建议，在正式录制/演示前完成三件事：

1. 进入 DataFinder 目录：终端切换到仓库下的 DataFinder 目录。

2. 验证数据库存在：执行ls databases/，应能看到三个 SQLite 数据库文件：

   • databases/hubspot.db（HubSpot CRM：公司、联系人、商机、营销邮件事件、营销活动）
   • databases/jira.db（Jira：项目、问题/工单、问题-客户关联、用户、评论、Sprint）
   • databases/dynamics365.db（Dynamics 365：客户、联系人、商机、产品、订单、系统用户）

   这三个库由 generate_data.py 生成，模拟虚构企业Contoso Ltd的同一批客户分布在三个系统中：不同列名、不同 ID、不同枚举，但通过共享的contoso_id作为跨系统身份桥（详见 DESIGN.md 第一部分）。

3. 准备演示 CLI：运行python demo.py --help（或直接python demo.py查看源码中的 demo.py 用法）。入口逻辑很简单：从命令行取一个问题，没有参数则交互式输入。

4. 准备 3～4 个示例问题：脚本推荐的提问包括"哪些商机有风险""基于支持工单看哪些商机有风险""华盛顿州最大的商机"等，方便在不同演示环节切换。

另外需要注意运行前提：DataFinder 的 LLM 调用通过 translator/llm_client.py 完成，按顺序尝试Azure OpenAI（AZURE_OPENAI_ENDPOINT+AZURE_OPENAI_API_KEY）→Anthropic（ANTHROPIC_API_KEY，模型claude-sonnet-4-20250514）→OpenAI（OPENAI_API_KEY，模型gpt-4o），任一可用即可。依赖清单见 requirements.txt。

三、Demo 1：简单查询（Simple Query）

第一个演示用最小问题验证"自然语言 → 结果"的完整链路：

python demo.py "which deals are at risk?"

对照 demo.py 的源码，这条命令会依次打印四个阶段并做解释：

1. Template Matching（模板匹配）：调用 translator/templates.py 中的match_template()。系统把问题连同模板库一起发给 LLM，要求对每个模板打出 0～100 的匹配分并抽取槽位值。系统提示词要求：score在 50 分以上才认为匹配，低于 50 或返回template_id == "none"则走回退路径。

2. Value Mapping（值映射）：调用 translator/value_mapper.py 中的map_values()。把槽位里的自然语言短语（如 "at risk"、"big deals"）翻译成本体过滤器，例如字典中预置了：

   • "big deals"→{"property": "ent:estimatedValue", "operator": "gt", "value": 100000}
   • "escalations"→{"property": "ent:ticketStatus", "operator": "eq", "value": "Escalated"}

   解析策略分三步：精确查找 → 部分匹配 → LLM 兜底（详见 FLOW.md 第二阶段）。

3. SQL Generation（SQL 生成）：由 translator/semantic_to_sql.py 的SemanticToSQLCompiler.compile()完成——这一步完全确定性、无 LLM，它读取映射文件把本体查询编译成针对真实表的 SQL。

4. Results（结果）：由 translator/execute.py 的run_query()在内存 SQLite 连接上执行（必要时ATTACH DATABASE挂载多个 .db 文件），返回商机列表（含状态与负责人）。

脚本的解说词很关键："All from a natural language question - no SQL required."（一句自然语言问题，全程不需要 SQL）。

四、Demo 2：跨系统查询（Cross-System Query）

第二个演示展示语义层真正的威力——一句话横跨两个系统：

python demo.py "which deals are at risk based on support tickets?"

对照源码与 FLOW.md 的执行过程，屏幕上会出现如下四个环节：

1. Template Match：LLM 打出 90+ 的高分，命中了deals_at_risk_support模板（该模板定义在 templates.py 中，模式为 "Which deals are at risk because of support issues"），同时抽取两个槽位：deal_filter（商机过滤条件）与support_signal（支持信号类型）。
2. Extracted Slots：识别出用户同时关心"商机"和"支持工单"两类实体。
3. Value Mapping：把 "at risk" 和 "support tickets" 映射为实际可执行的过滤器。
4. Multi-System Join：打印出的 SQL 同时 JOIN 了HubSpot 的商机表与Jira 的工单表。语义层知道：
   • 哪个库有商机（Dynamics 365 的d365_opportunities为 canonical 源，HubSpot 的hs_deals亦映射到ent:SalesOpportunity）；
   • 哪个库有支持工单（Jira 的jira_issues，且映射中带过滤条件——只有project_key = 'SUP'的项目才视为支持工单）；
   • 如何用共享的contoso_id把它们 JOIN 起来（本体上ent:SalesOpportunity.ent:customer与ent:SupportTicket.ent:affectedCustomer都指向schema:Organization）。

实际生成的 SQL 形态（来自 FLOW.md 第三阶段）大致为：

ATTACH DATABASE 'databases/jira.db' AS jira; ATTACH DATABASE 'databases/dynamics365.db' AS d365; SELECT jira.jira_issues.summary AS ent_ticketSummary, jira.jira_issues.priority AS ent_ticketPriority, jira.jira_issues.status AS ent_ticketStatus, d365.d365_accounts.name AS ent_affectedCustomer_schema_name FROM jira.jira_issues JOIN jira.jira_issue_customer_link ON jira.jira_issues.issue_id = jira.jira_issue_customer_link.issue_id JOIN d365.d365_accounts ON jira.jira_issue_customer_link.contoso_customer_id = d365.d365_accounts.contoso_id WHERE project_id IN (SELECT project_id FROM jira.jira_projects WHERE project_key IN ('SUP')) ORDER BY jira.jira_issues.created DESC;

返回的结果中，每个商机展示：商机名称与金额、当前阶段、关联工单数、商机负责人。这类查询在传统方式下需要编写自定义集成代码，而 DataFinder 只需要一句自然语言。

五、Demo 3：揭开语义层（Show the Semantic Layer）

第三个演示切换到文件视图，向观众解释"为什么能做到"：

ls mappings/

mappings/目录下是三个系统的 JSON-LD 映射文件（hubspot.jsonld 等），它们就是文档中说的 TMCF 映射（Template MCF，源自 Data Commons 传统），负责把各系统原生 schema 映射到共享的 Schema.org 本体上。脚本给出的对应关系示例：

• HubSpot 的hs_companies→schema:Organization；
• Dynamics 的Account（d365_accounts）→ 同样映射为schema:Organization；
• company_idvsAccountId（accountid）→ 都通过contoso_id归一到同一实体标识。

本体定义在 ontology/enterprise_schema.mcf：以schema:Organization、schema:Person、schema:Product、schema:Order等 Schema.org 类型为基础，用ent:命名空间扩展出ent:SalesOpportunity、ent:SupportTicket、ent:EngineeringIssue、ent:MarketingCampaign、ent:MarketingEngagement等企业类型，并定义相应的枚举（如OpportunityStatusEnum、TicketStatusEnum、PriorityEnum）。本体提供了跨系统的公共词汇表。

接着打开模板：

cat translator/templates.py | head -50

模板库（translator/templates.py）目前内置 6 个模板，定义常见查询模式：

• deals_at_risk_support："Which deals are at risk because of support issues"
• deal_pipeline："Show the sales pipeline or deal overview"
• customer_ticket_ranking："Which customers have the most support tickets"
• open_deals："Show open deals or opportunities"
• support_tickets："Show or list support tickets"
• pipeline_by_dimension："What is the pipeline value by<dimension>"

每个模板不仅是字符串模式，而是完整的执行计划：包含extract（槽位定义）、steps（检索步骤，每个步骤是一个语义查询 JSON）、slot_to_step（槽位与步骤的对应）、assemble（join/map/reduce/synthesize 装配阶段）。LLM 负责把用户问题匹配到模板并抽取变量部分（如 "at risk"、地区名），其余交给系统处理。

六、Demo 4：回退到 LLM（Fallback to LLM）

第四个演示验证容错能力——没有匹配模板时怎么办：

python demo.py "show me the largest deals in Washington state"

对照 demo.py 源码：match_template()返回template_id == "none"或score < 50时，控制台会打印 "No template matched. Falling back to direct LLM query planning."，然后走_fallback()路径：

1. translator/nl_to_semantic.py 的translate_to_semantic()把问题翻译成语义查询 JSON（primary_entity、select、filters、joins、aggregations、having、order_by等结构化字段，详见 DESIGN.md 第四部分）；
2. 同一个确定性编译器SemanticToSQLCompiler利用映射文件把语义查询编译成 SQL；
3. translator/execute.py 执行并返回结果，最后由 translator/summarize_results.py 生成自然语言摘要。

这就是脚本强调的混合策略（Hybrid Approach）："So you get the speed and reliability of templates when available, with LLM flexibility as a fallback."——有模板时享受模板的速度与可靠性，无模板时仍有 LLM 的灵活性兜底。

七、Demo 5：展示透明性（Show Transparency）

第五个演示回滚到前一条查询的输出，强调企业级采纳的关键：全透明（full transparency）。每条查询都会展示：

• 命中的模板及置信度分数（Matched: deals_at_risk_support (score: 92)这类输出）；
• 抽取的值及其映射方式（Extracted slots/Mapped filters两个 JSON 块）；
• 实际执行的 SQL（[step_id] SQL:逐行打印）；
• 原始结果加上 LLM 生成的摘要（--- Summary ---之后的部分）。

脚本里有一段很具说服力的台词：屏幕上的 SQL 可能同时在两个数据库的三张表上做 JOIN、带多个过滤条件——大多数业务用户写不出这样的 SQL，但他们可以用英文提问。可审计性是用户信任结果的前提。

关于装配阶段（对deals_at_risk_support这类复杂模板），translator/plan_executor.py 中的PlanExecutor.execute()还展示了完整的join → map → reduce → synthesize流水线：

• Join：确定性分组，按客户名把工单挂到对应商机下（无 LLM）；
• Map：对每个商机发起独立的 LLM 调用评估risk_level（high/medium/low），用ThreadPoolExecutor(max_workers=10)并行执行，每个调用上下文仅几百 token；
• Reduce：纯代码完成过滤、按风险等级与金额排序、截断前 15 条（无 LLM）；
• Synthesize：最后一次 LLM 调用，把最终结果写成 2～4 段的业务叙事摘要。

这种"并行 per-entity 小调用"的架构正是 ARCHITECTURE.md 强调的水平扩展思路：更多商机或更多数据源不要求更大模型、更大上下文，只要求更多并行的、喂给小模型的调用。

八、架构总结与 POC 规模

演示结尾展示 ARCHITECTURE.md，用四层结构收束：

1. Source Databases——HubSpot、Jira、Dynamics 365，各自原生 schema（对应databases/*.db）；
2. Ontology——基于 Schema.org 的公共词汇表（对应 ontology/enterprise_schema.mcf）；
3. TMCF Mappings——从原生 schema 到本体的声明式映射（对应 mappings/*.jsonld）；
4. NL Translator——把问题转成语义查询再转成 SQL（对应 translator/ 下的nl_to_semantic.py、semantic_to_sql.py、mapping_parser.py、plan_executor.py等模块）。

脚本给出的 POC 规模（以演示脚本表述为准）：

• 3 个数据库，300+ 条记录；
• 150 个跨系统映射实体；
• 10+ 个查询模板（当前 templates.py 实际内置 6 个，脚本描述的为演示口径）；
• 完整的跨系统 JOIN 能力；
• 全部实现约 2,000 行 Python。

两条关键设计约束（见 DESIGN.md 第七部分）值得向观众强调：一是SQL 编译必须确定性——同样的语义查询永远产生同样的 SQL，这证明"语义层让数据足够可读，以至于确定性编译器就能完成跨系统 JOIN"；二是LLM 只用在三个点：模板匹配（分类）、值映射（模糊查找）、per-entity 评估与可选摘要——绝不作为通用 schema 导航器。

九、典型业务用例（Use Cases）

脚本在结尾给出三组可直接演示的真实场景：

• Sales Ops（销售运营）："Show deals closing this quarter with open support issues"——本季度即将成交但存在未关闭支持问题的商机；
• Customer Success（客户成功）："Which customers haven't logged a ticket in 90 days?"——90 天未提交工单（可能流失）的客户；
• Executive（高管层）："What's our pipeline by region with engagement scores?"——按地区聚合的管道与参与度评分。

共同的价值主张是：在保持数据质量、安全性与可审计性的前提下，让企业数据通过自然语言触手可及。

十、演示要点强调（Key Points to Emphasize）

按脚本的建议，演示时应重点传达五条信息：

1. 问题：数据散落在不同 schema 的多个系统中；
2. 解决方案：共享本体之上的语义层；
3. 结果：跨系统的自然语言查询；
4. 透明性：用户能看到 SQL 并核验结果；
5. 混合策略：模板保证速度，LLM 保证灵活。

十一、录制与讲解的视觉技巧（Visual Tips）

• 终端要对比度高、字号够大，保证观众可读；
• 每次输出完重点内容后，用鼠标/光标高亮关键部分；
• 每次大输出之后稍作停顿，给观众阅读时间；
• 讲解代码与终端并用时使用分屏；
• 演示数据保持真实感但清晰易懂（如好记的公司名）。

十二、预期问题与回答（Questions to Anticipate）

脚本为演示者准备了四组高频问答：

十三、延伸阅读：从演示到源码

如果想进一步深入，建议按以下路径阅读仓库：

• demo.py：演示 CLI 入口，模板路径与回退路径的完整调用链；
• FLOW.md：以 "Which big deals are at risk because of escalated support tickets?" 为贯穿案例，逐阶段讲解模板匹配、值映射、SQL 编译、计划执行与装配，并给出每步的完整 SQL 与 JSON；
• ARCHITECTURE.md：模板式语义查询架构的完整理论：本体、两阶段流水线、装配的 join/map/reduce/synthesize 四阶段、模型路由与"为什么用模板而非自由查询规划器"；
• DESIGN.md：POC 实现指南——三库 schema 设计、数据生成规则、本体 MCF、TMCF 映射语法、语义查询语言规范与 LLM 提示词全文；
• translator/templates.py、translator/value_mapper.py、translator/plan_executor.py：模板库、值映射字典与执行器源码。

DataFinder 用约两千行 Python 证明了一个朴素的结论：企业数据集成不需要在每个系统之间硬编码胶水，而需要一层"公共语义"——模板负责稳定与速度，LLM 负责理解与兜底，本体与映射负责把一切落回真实的数据库表。这就是你在演示中看到的那句英文问题背后的全部机制。

• AI 应用
• MCP 服务
• AI Agent
• 后端
• 前端