GoogleCloudPlatform/knowledge-catalog · 上手攻略

仓库：GoogleCloudPlatform/knowledge-catalog
链接：https://github.com/GoogleCloudPlatform/knowledge-catalog
分类：database
作者：Tom
更新：2026-07-04

这是什么

这个仓库有两层含义，需要先区分清楚：

第一层（仓库名）： 仓库全名是 Google Cloud Knowledge Catalog（谷歌云知识目录），这是 GCP 的企业级数据目录服务（原名 Dataplex），提供动态知识图谱和元数据管理，为 AI Agent 提供语义上下文。

第二层（核心内容）： 这个 GitHub 仓库的真正核心是 Open Knowledge Format（OKF）——一个通用、厂商中立的知识表示格式，用纯 Markdown + YAML frontmatter 来结构化存储数据上下文、知识图谱和业务语义。

仓库还附带了一个参考实现 Agent，演示如何从 BigQuery 数据源自动生成 OKF Bundle，以及一个可视化工具，可将 Bundle 渲染成交互式 HTML 图谱。

截至 2026-07-04：Stars 5915，周增 +850，Apache-2.0 许可证，最近提交 2026-06-21。

解决什么问题

企业 AI 数据孤岛问题

当企业想把 AI Agent 接入私有数据时，通常面临： - 数据分散在 BigQuery、Spanner、对象存储等多个系统 - 语义上下文（表与表的关系、字段含义、业务逻辑）散落各处，Agent 难以理解 - 元数据存储在不同系统（Dataplex、Unity Catalog、Collibra），互不兼容

知识格式碎片化问题

目前每家厂商、每个框架都有自己的知识表示方式，导致： - 知识无法跨系统交换 - 知识无法版本控制 - 人类和 Agent 的可读性无法兼得

OKF 的核心理念

OKF 用"Markdown + YAML frontmatter 目录树"作为统一格式，实现： - 人类可读：直接 cat 就能看，无需 SDK - Agent 可解析：无需定制 SDK，标准文本处理即可 - Git 版本控制：知识变更变成 Pull Request - 无厂商锁定：一个目录，可以放到任何地方 - 渐进式上下文加载：自动生成的 index.md 支持逐层导航

快速安装

前置依赖：Python 3.13+，BigQuery 访问权限，Gemini API Key 或 Vertex AI 权限

# 克隆仓库
git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog

# 创建虚拟环境并安装
python3.13 -m venv .venv
.venv/bin/pip install --index-url https://pypi.org/simple/ -e .[dev]

# 认证配置（BigQuery 读取公开数据集无需认证）
gcloud auth application-default login

# 设置 GCP 项目（用于计费）
gcloud config set project <your-project-id>

# 配置 Gemini（方案 A：AI Studio）
export GEMINI_API_KEY="your-api-key"

# 或方案 B：Vertex AI（适合企业）
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="<your-project-id>"
export GOOGLE_CLOUD_LOCATION="us-central1"

无需安装的场景：直接浏览仓库中预制的示例 Bundle（GA4/Stack Overflow/Bitcoin），无需任何配置。

核心用法

用法一：直接浏览预制 OKF Bundle（无需运行任何代码）

仓库内置了三个已生成的 Bundle，直接看效果：

Bundle	路径	可视化文件
GA4 电商数据	`okf/bundles/ga4/`	viz.html
Stack Overflow	`okf/bundles/stackoverflow/`	viz.html
Bitcoin 区块	`okf/bundles/crypto_bitcoin/`	viz.html

打开 viz.html 可看到：节点图谱（按类型着色）+ 概念详情面板 + 反向链接 + 搜索过滤。

用法二：从 BigQuery 数据源生成自己的 OKF Bundle

第一步：准备种子 URL（web enrichment 用，可选）

创建 seeds.txt，每行一个权威文档 URL：

https://support.google.com/analytics/answer/11990039
https://developers.google.com/analytics/bigquery

第二步：运行 enrichment agent（BQ + Web 双通道）

.venv/bin/python -m reference_agent enrich \
    --source bq \
    --dataset <project>.<dataset> \
    --web-seed-file ./seeds.txt \
    --out ./bundles/my_data

BQ Pass：读取 BigQuery 元数据（表、字段、描述），生成 OKF 概念文档
Web Pass：Gemini Agent 作为爬虫，从种子 URL 开始抓取权威文档，补充到已有概念或新建 references/ 文档
--no-web：跳过 Web Pass，只跑 BQ

第三步：聚焦单个概念迭代

.venv/bin/python -m reference_agent enrich \
    --source bq \
    --dataset <project>.<dataset> \
    --concept tables/events_ \
    --out ./bundles/my_data

用法三：可视化任意 Bundle

.venv/bin/python -m reference_agent visualize \
    --bundle ./bundles/my_data \
    --out ./bundles/my_data/viz.html \
    --name "My Data"

生成一个自包含 HTML 文件（无后端，CDN 加载 Cytoscape.js + Marked.js），可直接分享或提交到仓库。

OKF 文件格式（核心知识点）

每个概念是一个 .md 文件，顶部是 YAML frontmatter：

---
type: BigQuery Table              # REQUIRED：概念类型
title: Customer Orders             # 推荐：显示名
description: 每行代表一个已完成订单  # 推荐：单行摘要
resource: https://console.cloud.google.com/bigquery?...  # 资产 URI
tags: [sales, orders]             # 推荐：标签列表
timestamp: 2026-05-28T14:30:00Z  # 推荐：最后修改时间
---

# Schema

| 列名      | 类型    | 描述                  |
|----------|---------|----------------------|
| order_id | STRING  | 全局唯一订单 ID       |

# Joins

与 [customers](/tables/customers.md) 表在 customer_id 上 JOIN

目录结构约定：

bundle/
├── index.md              # 自动生成的目录列表
├── log.md                # 可选的变更历史
├── tables/               # 业务概念分类
│   ├── orders.md
│   ├── customers.md
│   └── index.md
└── references/           # 外部参考资料
    └── ga4-docs.md

交叉链接（通过标准 Markdown 链接表达关系）：

与 [customers](/tables/customers.md) 表在 `customer_id` 上 JOIN

典型适用场景

场景	价值
企业 AI 数据上下文	让 Agent 在不移动数据的情况下，理解 BigQuery/Spanner 等系统中表的语义关系
知识迁移/交换	不同组织用同一格式交换数据目录，摆脱 Dataplex/Unity Catalog/Collibra 锁定
数据治理文档化	自动从 BigQuery 元数据生成可版本控制的数据字典
AI 应用上下文工程	生成结构化上下文文档，输入给 LLM 做 RAG
团队知识共享	工程师直接 `cat` 看表含义，不需要查 Confluence

坑与注意

Python 3.13 是硬性要求：仓库使用依赖项需要 Python 3.13+，3.12 及以下会安装失败。
Web Pass 有爬取风险：Gemini Agent 作为爬虫时，会自动跟踪同域名链接，可能爬取大量页面。建议设置 --web-allowed-host 限制域名，并设置 --web-max-pages 限制页数。
BigQuery 公开数据集也会计费：调用者的 GCP 项目会被计费，即使查询的是公开数据集。建议在测试时用 --dry-run 或监控配额。
viz.html 需要 CDN 访问：可视化 HTML 依赖 Cytoscape.js 和 Marked.js 从 CDN 加载，离线环境无法渲染图谱，但 Markdown 内容仍可读。
OKF 是 Draft v0.1：格式尚未稳定，spec 明确标注为草稿，生产使用需注意未来可能breaking change。
Agent 生成质量依赖 LLM：enrich 出来的文档质量受 Gemini 模型能力影响，生产使用前建议人工审核。
仓库 Stars 较低（5915）：与 system_prompts_leaks 等 48K 仓库相比生态较小，踩坑时社区资源有限。

与同类对比

方案	格式	厂商锁定	版本控制	生成方式	适用场景
OKF（本仓库）	Markdown+YAML	无	Git 原生	BigQuery Agent + Web爬虫	通用知识交换、AI 上下文
Dataplex / Knowledge Catalog	厂商格式	Google Cloud	需导出	UI/API 配置	GCP 企业内部
Unity Catalog	厂商格式	Databricks	需导出	Delta Sharing	Databricks 生态
Collibra	厂商格式	Collibra	无	人工录入	大型企业数据治理
DataHub	OpenAPI/GraphQL	无	etcd	Push/Pull 集成	数据发现而非知识交换

OKF 的独特价值在于厂商中立 + Git 版本控制 + 人类可读，尤其适合需要跨组织知识共享或 AI 应用上下文工程的场景。

一句话推荐结论

如果你在构建需要跨数据源语义的 AI 应用，或者受够了数据字典散落在 Confluence/Dataplex/数据库注释里——OKF 用一个 Git 目录解决所有问题，值得作为企业内部知识交换的事实标准先试起来。