跳转至

上下文接口：AI Context APIs

本章所属 DDA 层：AI Context APIs

给仓外系统一套「自己写 SQL、自己查 SPARQL、自己扫向量」的权限，和只暴露四种稳定数据形态，是两条路。前者把语义护栏拆掉。后者才是面向智能体的数据契约（Data-for-Agent）。

可靠性上限由契约决定，不由仓外用了哪个编排框架决定。本书不建造 Agent，也不写报告生成。本层交付的是消费方能依赖什么，以及缺什么时必须看到缺失声明。

问题

前面各层已经能落湖、登记资产、解析身份、存放已验证关系和检索证据。若消费方仍直连裸库，口径会在末端被重写一遍：有人把 preclinical 算进在研，有人用公开 ID 当主键，有人把 extracted 当真理。

语义层在本书中不是 BI 指标平台。它是 Ontology 的工程化访问面。指标口径若需要统一，应回到本体受控词表，而不是另建一套给人看报表的语义模型当主契约。

传统方案

传统消费是分析师写 SQL，或给早期机器人一个数据库账号。再往后，是把指标定义搬进 BI 语义层或通用指标引擎，再经 MCP 暴露 query_metrics。

阿斯利华若只问「在研化合物有多少」，指标引擎能帮忙。若问「ASH-001 的身份、已验证靶点、3.2 节证据和我有没有权看」，指标引擎答不全，也不该被拉去冒充世界模型。

为什么失效

裸 SQL 随字段改名崩。裸 SPARQL 把命名图和许可细节推给每个调用方。裸向量 API 没有引用合同。

BI 语义层服务人读报表，容忍人工兜底。仓外机器消费要求版本、缺失声明和许可同源。把通用指标引擎当成本书的语义层，会漏掉身份、证据树和 extracted ≠ validated。

在仓内做编排，看起来像「AI 平台」。它把不可靠语义重新引入末端：提示词里的私货口径、工具自循环、把湖表当记忆。那是应用，不是基座。

flowchart LR
    EXT[仓外消费方] --> API[上下文接口]
    API --> P[ContextPack]
    API --> E[Evidence]
    API --> C[ValidatedClaim]
    EXT2[仓外消费方] --> RAW[裸SQL_SPARQL_向量]
    RAW --> X[口径自造]

图：消费方走契约，不走裸后端（DDA 层：AI Context APIs）

新的设计思想

对外只暴露版本化数据形态。推荐四种：Document、Evidence、Claim、Context Pack。

推理吃 Pack，检索吃 Evidence。不要用「再搜一遍」顶替已治理上下文。

Context Pack 必带身份、关系、证据树、许可声明、missing[]、本体发版号。缺后端字段写 missing，不编造，不用 YAML 冒充运行时。

extracted 默认不进推理包。需要时显式打开，并让调用方知道这是候选。

MCP 是通道，不是本层定义。换通道，契约还在。

架构设计

flowchart TB
    EXT[仓外消费方] --> API[版本化Context_APIs]
    API --> RES[解析身份]
    RES --> PACK[ContextPack]
    PACK --> EV[检索或还原证据]
    EV --> FB[提交反馈]
    API --> ONT[Ontology]
    API --> KG[ScientificKG]
    API --> IDX[EvidenceIndex]
    API --> CAT[Catalog]
    API -.拒绝.-> RAW[裸后端]

图：推荐调用顺序与拒绝面（DDA 层：AI Context APIs）

工程实践

决策表

决策 选择 放弃
对外形态 Document / Evidence / Claim / Context Pack 万能 search、裸 SQL、裸 SPARQL、裸向量
推理 Pack + missing[] 缺字段时编造或静默省略
候选知识 默认不进 Pack ingest 自动当知识
通道 MCP / REST 仅为实现 把通道协议当成本层
Agent 仓外消费方 仓内编排、技能包、报告生成
指标 本体受控词表 用 BI 语义层替换身份与证据

阿斯利华可走通的例子

推荐顺序：

resolve("savolitinib")
  → ASH:ENT:DC:savolitinib
get_entity_context(ASH:ENT:DC:savolitinib)
  → Pack
search_evidence / restore_context
  → csr_ash001_phase1_v3#3.2.t1
submit_feedback
  → 闭环信号

Pack 的稳定字段：

pack_version: "1.0"
identity:
  enterprise_id: ASH:ENT:DC:savolitinib
  entity_kind: DrugCandidate
  preferred_label: savolitinib
  ontology_release_id: 2026.08.1
relations:
  targets: [ASH:ENT:TG:met]
evidence_tree:
  - chunk_id: csr_ash001_phase1_v3#3.2.t1
license:
  policy: filter_at_candidate_generation
missing: []

实体未找到时仍返回 Pack：found=false，missing 含 entity。图谱不可达时写 missing: [graph]，禁止用目录 YAML 填关系假装成功。

「在研化合物数」若要对齐报表，口径必须与本体词表的 ontology_release_id 相同。通用指标引擎可以是实现选择，但不能成为第二套「在研」定义。

失败模式

  • 消费方直连湖表：字段一改，全部提示词重写，且绕过许可。
  • Pack 缺字段却不声明：模型补全成「事实」。
  • extracted 默认进入推理：候选不良反应被写成说明书结论。
  • 用检索工具顶替 get_entity_context：每次回答换一套邻居。
  • 把平台聊天入口当成本层：入口可以换，契约不能换。

业界路线对照

Open PHACTS 的 Core API 让应用坐在整合层之上，而不是直连各源。复星一类「Data for Agent」岗位讨论的是分层数据形态与接口规范，不是再做一个业务门户。阿斯利康的科研助手是仓外消费方：它消费知识地图和文献，不定义基座。本书到 API 为止。

BI 语义层、通用指标引擎、平台内置对话，都可以作为对照。它们解决「人读数」或「指标 SQL」，不解决企业主键、证据树和缺失声明。

最佳实践

契约版本化。字段变更可观测，禁止静默加字段当新合同。

推理与检索分开。

许可同源。Pack 里的证据必须是候选期过滤后仍可见的。

失败要大声。后端不可达就声明 missing 或硬失败。

不在本层教编排。该用工作流的固定检查，留给应用团队；基座只保证每一步能调到同一套身份和出处。

延伸阅读

  • Data-for-Agent：分层数据形态与版本化接口，而不是提示词目录。
  • MCP：作为通道的规范，不是语义层定义。
  • Open PHACTS Core API：应用与整合层分离。

Checklist

  • 消费方是否只经版本化接口取数，未直连裸库、裸 SPARQL、裸向量？
  • 是否提供 Context Pack，并且缺后端时写 missing[]？
  • extracted 是否默认不进推理包？
  • 推理与检索是否分工？
  • 是否澄清本书语义层与 BI 语义层的区别？
  • MCP 是否只被当作通道？
  • 本章是否避免写成 Agent 编排或报告生成教程？

从裸后端和 BI 语义层，收到四种数据形态。消费方能依赖的是契约，不是某个编排框架。