sample-okf-llm-wiki

# 数据百科：面向 AWS 数据的 AI 知识包，通过 MCP 提供给代理 **数据百科** 将 AWS Glue 数据库转换为可移植的知识包，并通过模型上下文协议（MCP）为 AI 代理提供服务。它读取 Glue 目录，由大型语言模型（LLM）编写一组描述每个数据集的 markdown 文档，包括表、连接、指标和已知问题。它在目录更改时保持这些文档同步，并通过 MCP 服务器将它们暴露给代理。结果是：代理不仅了解 *存在哪些列*，还了解 *您的数据含义*。 这些知识包是开放知识格式（OKF）包 - 一个知识包是一个 markdown 文件目录，带有 YAML 前置信息。数据百科将 OKF 模型映射到 AWS，格式为 `数据域 → 数据集（Glue 数据库）→ 表`。代码标识符、资源名称和环境变量中的 `okf`/`OKF_` 前缀指的是格式，而不是产品。 **注意：** 这是一个示例实现，提供用于教育和演示目的。您应该在部署到任何环境之前，审查、测试和自定义此代码以满足您的特定需求。 --- ## 快速链接 - 📚 [使用控制台](./quick-start-guide/using-the-console.md) — 注册数据集、收获和浏览知识包 - 🔌 [连接代理（MCP）](./quick-start-guide/connect-an-agent.md) — 颁发凭证并从代理查询知识包 - 🚀 [快速入门](#getting-started) — 先决条件和一键部署 - 🏗️ [架构](./docs/ARCHITECTURE.md) — 各个组件如何组合以及背后的原因 - 📐 [约定](./docs/CONVENTIONS.md) — 服务之间的契约（S3 布局、DynamoDB 形状、环境变量） - 📘 [API 参考](./docs/API_REFERENCE.md) — 代码编写所针对的外部 API 形状 --- ## 功能 - **自动归纳** - AI 代理读取您的 Glue 目录，采样真实数据，并编写描述表、连接、指标和已知问题的知识包。 - **基于文档** - 附加您自己的源文档（DDL、数据字典、运行手册、规范），以便知识包反映您组织的知识，而不仅仅是原始模式。 - **自我修复新鲜度** - Glue 目录更改会自动触发范围重新收获，语义搜索索引在每次写入时保持与知识包同步。 - **通过 MCP 提供服务** - 任何支持 MCP 的代理都可以通过 `list_domains`、`list_directory`、`read_page`、`glob`、`grep`、`get_backlinks` 和 `semantic_search` 发现、读取和语义搜索您的知识包。 - **机器凭证** - 颁发范围 OAuth2 凭证，以便应用程序和代理可以编程方式调用 MCP 服务器。 - **Web 控制台** - 注册数据集、上传上下文文档、运行和监视收获、浏览知识包以及从 React UI 资源图中探索链接。 --- ## 架构 ### 解决方案架构 <p align="center"> <img alt="数据百科解决方案架构" src="./assets/architecture.png" width="900"> </p> **使用的 AWS 服务：** - Amazon S3（知识包存储）和 S3 Vectors（语义索引） - AWS Glue（源目录）和 Amazon Athena（数据采样） - Amazon Bedrock（Claude 用于归纳，Titan V2 用于嵌入） - Amazon Bedrock AgentCore Runtime（收获 + 消费 MCP） - AWS Lambda（控制 API、重新索引、增量） - Amazon API Gateway（HTTP API）和 Amazon Cognito（身份验证） - Amazon EventBridge + Amazon SQS（事件驱动的新鲜度） - Amazon DynamoDB（注册、鲜度、凭证） - Amazon CloudFront（SPA 投递） ### 仓库布局 ``` data-wiki/ ├── services/ │ ├── okf_core/ # 纯 Python OKF 原语（无 AWS 或代理依赖） │ ├── okf_aws/ # 共享 boto3 助手：Titan 嵌入、S3 Vectors、S3 密钥 │ ├── harvest/ # 归纳：AgentCore 上的 deepagents 代理 │ ├── reindex/ # 鲜度：S3 事件 → S3 Vectors Lambda │ ├── incremental/ # Glue 更改 → 范围重新收获 + 每夜协调 │ ├── control_api/ # Cognito 授权的 REST（API GW + Lambda） │ └── consumption_mcp/ # AgentCore 上的流式 HTTP MCP 服务器 ├── infra/ │ ├── durable/ # S3 存储桶、S3 Vectors 索引、Cognito、DynamoDB │ ├── compute/ # Lambda、API GW、AgentCore 运行时 + IAM、EventBridge/SQS、CloudFront │ └── modules/lambda/ # 可重用的 zip-Lambda + 最小权限角色 ├── ui/ # React SPA（JS）、shadcn/ui + Tailwind、Cognito OIDC ├── okf-mcp/ # Claude Code 插件：连接代理到 MCP 服务器 ├── scripts/ # run_tests.sh、build_lambdas.sh、deploy.sh ├── quick-start-guide/ # 控制台使用任务导向指南 └── docs/ # ARCHITECTURE.md、CONVENTIONS.md、API_REFERENCE.md ``` 参见 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)，了解各个组件如何组合以及背后的原因。 --- ## 快速入门 ### 先决条件 **所需工具：** 必须在您的本地机器上安装以下工具： - [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 配置了[适当的凭证](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) - [Terraform CLI](https://developer.hashicorp.com/terraform/install) - [Docker](https://docs.docker.com/engine/install/) 运行（带有 `buildx` 进行 ARM64 镜像构建） - [Node.js](https://nodejs.org/en/download) 和 npm - [Python](https://www.python.org/downloads/) （v3.12 或更高版本） - [jq](https://jqlang.org/download/) **AWS 设置：** - **预先创建的、版本化的 S3 存储桶** 用于 Terraform 状态（部署使用分离状态，不会为您创建）。 - **Amazon Bedrock 模型访问** 在您的区域中启用 Claude 归纳模型和 Amazon Titan 文本嵌入 V2。请按照[此处](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)的说明进行操作；如果没有访问权限，您将在收获过程中收到 `AccessDeniedException`。 - 至少一个 **AWS Glue 数据库** 包含您要收获的表。 > **注意：** 此堆栈使用 S3 Vectors 和 Bedrock AgentCore Runtime。请在部署前验证它们在您的目标区域是否可用。 ### 安装和部署 1. **克隆仓库** ```bash git clone <您的仓库网址> cd sample-okf-llm-wiki ``` 2. **验证 AWS** ```bash # 选项 I：导出 AWS 临时凭证 export AWS_ACCESS_KEY_ID="您的临时访问密钥" export AWS_SECRET_ACCESS_KEY="您的临时秘密密钥" export AWS_SESSION_TOKEN="您的临时会话令牌" export AWS_DEFAULT_REGION="您的区域" # 选项 II：导出 AWS 配置文件 export AWS_PROFILE="您的配置文件名称" ``` 3. **运行部署** ```bash ./scripts/deploy.sh # 完整管道（首次运行时提示） ``` 在**首次运行**时，您将被提示输入： - AWS **区域** - **Terraform 状态存储桶** 名称（预先创建，版本化） - **初始管理员用户** （电子邮件和姓名） 这些信息将保存到 `scripts/.deployment.config` 并在后续运行中重用。然后，部署运行所有五个阶段：推送容器镜像，应用两个 Terraform 堆栈，将 CloudFront URL 绑定到 Cognito，并同步 SPA。 > **注意：** 管理员用户将在 Cognito 用户池中从您的输入创建；Cognito 将临时密码通过电子邮件发送到该地址。 ### 访问控制台 成功部署后，打印已部署的 URL： ```bash ./scripts/deploy.sh summary ``` 打开 CloudFront URL，使用您的电子邮件中的管理员凭证登录，并按照 [使用控制台](./quick-start-guide/using-the-console.md) 注册您的第一个数据集并运行收获。 --- ## 配置选项 ### 部署阶段 `deploy.sh` 协调整个管道，但每个阶段都可以单独运行 - 对于迭代单个层而无需重新运行所有操作非常有用： ```bash ./scripts/deploy.sh <durable|images|compute|cognito-urls|ui|summary|destroy> ``` | 阶段 | 它执行的操作 | | -------------- | ---------------------------------------------------------------------------- | | `durable` | S3 存储桶、S3 Vectors 索引、Cognito、DynamoDB（长期堆栈）。 | | `images` | 构建并将收获 + 消费容器镜像推送到 ECR。 | | `compute` | Lambda、API Gateway、AgentCore 运行时、EventBridge/SQS、CloudFront。 | | `cognito-urls` | 重新应用持久层以将 CloudFront URL 注入 Cognito。 | | `ui` | 构建 React SPA 并将其同步到 S3 / CloudFront。 | | `summary` | 打印已部署的 URL。 | | `destroy` | 拆除所有内容（提示确认）。 | 部署处理了几项原本需要手动完成的任务： - 捕获运行时的 **VPC** （2 个私有子网 + NAT）是自动配置的，因为 S3 文件挂载需要 VPC 网络。您可以使用 `TF_VAR_harvest_vpc_subnet_ids` / `TF_VAR_harvest_vpc_security_group_ids` 使用您自己的 VPC。 - **S3 文件** 文件系统、挂载目标和访问点由 Terraform 管理，并挂载在 `/mnt/data`。 - Cognito **回调/注销 URL** 通过 `cognito-urls` 重新应用获取 CloudFront URL，而不是控制台。 - 镜像 URI 和 CloudFront URL 在各个阶段之间通过 `.deployment.config` 和 Terraform 输出传递。 ### 连接代理（MCP） 一旦知识包被收获，代理就会通过 MCP 服务器消费它们。在控制台的**凭证**视图中颁发机器凭证，然后连接： - **从 Claude Code** - 使用捆绑的 [`okf-mcp`](./okf-mcp/) 插件，它自动处理令牌刷新。 - **从任何 MCP 客户端** - 在 Cognito 令牌端点交换您的凭证以获取持有者令牌，并直接调用运行时。 参见 [连接代理（MCP）](./quick-start-guide/connect-an-agent.md)，了解两种路径。 ### 本地 UI 开发 在 `localhost` 上针对已部署的后端运行控制台： ```bash cd ui npm run dev:env # 从计算堆栈输出写入 ui/.env.local npm install # 仅首次运行 npm run dev # http://localhost:5173 ``` 端口 `5173` 在 Cognito 中被允许用于 OIDC 重定向，因此本地开发可与真实的已部署 Cognito 和控制 API 配合使用。有关详细信息，请参见 [`ui/README.md`](./ui/README.md)。 --- ## 运行测试 测试套件完全离线运行：`moto` 模拟 S3 和 DynamoDB，其余客户端（s3vectors、bedrock-runtime、glue、athena、agentcore）被注入假数据。没有实时 AWS 调用。 ```bash python3 -m venv .venv && source .venv/bin/activate pip install -e services/okf_core -e services/okf_aws # 共享库 pip install -e services/harvest -e services/reindex -e services/incremental \ -e services/control_api -e services/consumption_mcp --no-deps pip install pytest "moto[s3,dynamodb]" ./scripts/run_tests.sh # 单元测试 + 离线端到端收获测试 cd ui && npm ci && npm run build cd ../infra/durable && terraform init -backend=false && terraform validate cd ../compute && terraform init -backend=false && terraform validate ``` `tests/test_e2e_harvest_offline.py` 驱动非 LLM 半部分的收获管道端到端（Glue 源 → 守护引擎 → 链接图影响分析 → `finalize_bundle`），针对伪造的 F1 形状的 Glue/Athena 源，并断言输出是有效的 OKF 知识包。实际的 Bedrock 调用、S3 Vectors 查询和 AgentCore 托管需要一个真实的账户，这里不进行测试。 --- ## 清理 拆除部署创建的所有内容： 1. **导出 AWS 凭证** （与上面的部署步骤相同）。 2. **运行销毁阶段：** ```bash ./scripts/deploy.sh destroy ``` 这会拆除两个 Terraform 堆栈（持久和计算）。Terraform **状态存储桶** 您预先创建的不会被部署管理 - 如果您不再需要，可以手动删除。 > **警告：** 这会永久删除收获的知识包、向量索引和所有注册表/凭证状态。底层 Glue 数据库及其数据不会被触及。 --- ## 贡献 有关更多信息，请参见 [CONTRIBUTING](./CONTRIBUTING.md)。 ## 许可证 该项目根据 MIT 许可证获得许可。有关详细信息，请参见 [LICENSE](./LICENSE) 文件。 ## 作者 以下作者为 AWS 提供了此示例，并在开源发布前进行了准备： - [Edvin Hallvaxhiu](https://github.com/edvinhallvaxhiu) - [Aubrey Oosthuizen](https://github.com/a13zen) - [Rahul Shaurya](https://github.com/shauryarahul) - [Sindi Cali](https://github.com/scali123) - [Shukhrat Khodjaev](https://github.com/khodjaevsh) - [Ravi Kiran Ganji](https://github.com/RaviGanjiAWS) 特别感谢 [Bruno Dhefto](https://github.com/dhefto) 对此解决方案的详细审查和建议，这些帮助改进了该解决方案。