Context Ontology Accelerator 是一个开源的、基于本体（ontology）的语义上下文加速器，部署在 AWS 上，让 AI Agent 做出更准确、一致且可解释的决策。很多新手第一次执行make deploy-dev就会栽在三个地方：账号配额不够、x86 机器上 ARM64 构建报exec format error、以及OpenSearch Serverless 等资源的持续计费。这篇指南按“环境准备 → 配额检查 → ARM64 构建 → 部署 → 成本避坑”的顺序，带你完整走一遍。

🧭 部署流程速览

整个部署由一条命令驱动，背后分为四个阶段：

全流程入口是 scripts/deploy.sh，由 Makefile 的deploy-dev目标调用。预检脚本 scripts/preflight-deploy.sh 会在 CDK 运行前拦住绝大多数可预见的失败——养成先跑make preflight的习惯，能省下大量回滚时间。

📋 环境准备：前置条件与工具链

官方要求的前置条件（完整版见 external-docs/content/deploying.md）：

推荐使用mise一键安装全部固定版本，然后执行初始化：

git clone https://gitcode.com/gh_mirrors/co/context-ontology-accelerator cd context-ontology-accelerator curl https://mise.run | sh mise install make setup # 内部先跑 Smithy 代码生成，再装 uv/pnpm 依赖

💡make deploy-dev会自动复检工具链版本，并在smithy-generated/缺失或过期时自动重新生成产物，所以一般不需要手动干预。

🔍 配额检查：两个硬伤 + 一个最容易被忽略的坑

预检自动覆盖的两项硬配额

新账号（尤其是 sandbox 账号）最容易卡住的两项配额，预检脚本会自动验证：

第二条是经典的“部署 30 分钟后才失败”的坑：部分新账号的 Lambda 并发配额被降到了 10，此时任何并发预留都会被拒绝。手动确认命令：

aws ec2 describe-vpcs --query 'length(Vpcs)' --output text aws lambda get-account-settings \ --query 'AccountLimit.[ConcurrentExecutions,UnreservedConcurrentExecutions]'

如果遇到Specified ReservedConcurrentExecutions for function decreases account's UnreservedConcurrentExecution below its minimum value of [10]这类报错，快速解锁方式是：

SCL_LAMBDA_RESERVED_CONCURRENCY=0 make deploy-dev

最容易被忽略的坑：Fargate vCPU 配额只有 6

预检不覆盖、但真实会卡死部署的配额中，最紧的一个是Fargate 按需 vCPU 数量（L-3032A538），AWS 默认仅 6：

• VKG（虚拟知识图谱）为每个 namespace 各跑一个 Fargate 服务；
• 加上一个 2 vCPU 的富集任务和两个 namespace 的 VKG 服务，就能耗尽默认配额。

查询自己账号的实际配额值：

aws service-quotas get-service-quota --service-code fargate --quota-code L-3032A538 \ --query 'Quota.[QuotaName,Value]' --output text

⚠️ 配额提升不一定即时生效——Lambda 并发提升会创建 AWS Support 工单。如果你今天就要部署，优先用文档中给出的绕行方案（如上面的SCL_LAMBDA_RESERVED_CONCURRENCY=0），而不是等审批。

其余值得在新账号上确认的配额（OpenSearch Serverless OCU、Bedrock 每模型调用量、Neptune 实例数等）及原因，完整清单在 external-docs/content/deploying.md 的“Appendix A.3 Quotas to check before deploying”一节，建议对照自己的预期 namespace 数量逐一核对。

🐧 ARM64 构建避坑：x86 机器上的exec format error

为什么需要 ARM64

项目中多个 CDK 资产（Context Manager/Serve、MCP、VKG 镜像）明确构建为linux/arm64。在原生 ARM64 机器上毫无问题，但在 x86_64 的 Linux 主机上，Docker 必须先注册 binfmt/QEMU 模拟，否则构建步骤会直接报：

exec format error

验证与修复三步走

第一步：验证当前 builder 是否支持 ARM64

docker buildx inspect --bootstrap docker run --rm --platform linux/arm64 alpine uname -m # 应输出 aarch64

第二步：如不支持，注册 ARM64 模拟器（需要特权容器）

docker run --privileged --rm tonistiigi/binfmt --install arm64

Docker Desktop 在支持的平台上自带多平台模拟，通常无需此步。

第三步：再次验证后再部署

docker run --rm --platform linux/arm64 alpine uname -m make deploy-dev

如果仍然失败，按这个顺序排查（与官方文档一致）：

1. 确认CDK_DOCKER指向的引擎（Docker 或 Finch）——模拟要注册在CDK 实际使用的那个引擎上；
2. 重新执行docker buildx inspect --bootstrap，确认linux/arm64出现在平台列表中；
3. 如果 Alpine 验证命令本身报exec format error，那是宿主机/模拟问题，与 CDK 和应用代码无关；
4. 使用远程或自定义 builder 时，用docker buildx ls检查的是哪个 builder——在本地默认引擎上注册不会自动作用于其他 builder。

⚠️ binfmt 安装会修改宿主机内核配置（特权容器），请遵循你们的主机安全策略。如果组织不允许，替代方案是：用原生 ARM64 构建机，或提供预构建的 ARM64 ECR 镜像（通过context_manager_image_uri、vkg_image_uri+ecr_repository_arn传入），跳过本地构建。

🌍 区域选择：为什么 us-east-1 总是“在场”

Context Ontology Accelerator 依赖 Bedrock AgentCore Runtime、DataZone/SMUS、Neptune、OpenSearch Serverless、Bedrock+Guardrails、Athena 等服务的交集，因此并非所有区域都能部署。部署前请先在目标区域核对这些服务的可用性（详见 external-docs/content/deploying.md 的 Region Prerequisites 一节）。

两个关键约束新手必读：

1. 区域变量要成对设置。AWS_DEFAULT_REGION（AWS CLI/预检用）和CDK_DEFAULT_REGION（CDK 用）必须一致，否则 CDK 和 CLI 会静默指向不同区域：

export AWS_DEFAULT_REGION=us-west-2 export CDK_DEFAULT_REGION=us-west-2

2. 非 us-east-1 部署需要两次 bootstrap。*-edge-waf栈（CloudFront 级 WAF WebACL 和 CloudFront ACM 证书）永远部署在us-east-1，所以：

npx cdk bootstrap aws://<ACCOUNT_ID>/<你的区域> npx cdk bootstrap aws://<ACCOUNT_ID>/us-east-1 # 永远需要

💡 另外注意：默认模型 ID 全部是us.前缀的跨区推理配置文件（如us.anthropic.claude-sonnet-5），在美国以外区域无法调用。cdk synth和预检会在部署前检查并报错，修复方法是在 SSM 配置/{prefix}/config中设置bedrockLlmModelId、bedrockEmbedModelId等键。注意嵌入模型只能在首次部署时确定——更换嵌入模型等于全量数据迁移，且向量维度在索引创建时就固定了。

🚀 执行部署：一条命令跑完 16 个 Stack

预检通过后，正式部署只有一条命令：

make deploy-dev

它会先部署平台栈，再部署 Databricks SQL Warehouse 连接器（顺序不可颠倒——连接器要从 SSM 读取平台发布的角色 ARN，平台未部署会直接以COA does not appear to be deployed退出）。

部署的 16 个栈一览（前缀coa-dev-，可用SCL_PREFIX自定义）：

耗时预期：全新部署约1.5 小时（Neptune、OpenSearch Serverless 的供给与 AgentCore Runtime 初始化是大头，多个栈并行进行）。首次部署另需额外预算：mise 工具链安装、uv sync/pnpm install、Smithy/Gradle 首次生成（会下载 Gradle wrapper）、Docker 镜像构建和 CDK bootstrap。看起来“卡住不动”时，先用aws cloudformation list-stacks查看状态，大概率是在等 Neptune 或 OpenSearch。

常用部署变量（完整列表见官方文档 Configuration Options 一节）：

SCL_PREFIX=myproject make deploy-dev # 自定义资源前缀（默认 coa） SCL_VPC_ID=vpc-abc123 make deploy-dev # 复用现有 VPC SCL_SMUS_ADMIN_ARNS=arn:aws:iam::123456789012:role/... make deploy-dev

其中SCL_SMUS_ADMIN_ARNS在没有名为Admin的 IAM 角色的账号（例如 IAM Identity Center 账号）上是必选项，否则预检会快速失败并给出明确报错。

部署成功后：

1. 创建第一个用户：aws cognito-idp admin-create-user --user-pool-id <POOL_ID> ...（用户池 ID 在coa-dev-auth栈输出或 SSM/<prefix>/userpool-id）；
2. 打开 Web 应用：URL 在coa-dev-web栈的 CloudFormation 输出WebAppUrl中；
3. 授予权限：给管理员授予platform-admin平台级角色。

💰 成本避坑：四个最容易超支的点

坑 1：OpenSearch Serverless 闲置也计费

向量库是NEXTGEN集合组的 VECTORSEARCH 类型，强制启用 standby 副本（会使 OCU 消耗约翻倍），且 Serverless 按最低 OCU 分配计费——即使你一次查询都不发。一个闲置的评估环境也会持续产生这部分账单。

容量由 CDK context 值aoss_min_ocu（默认 2）和aoss_max_ocu（默认 96）控制，综合（synth）阶段就会校验取值合法性。纯成本敏感的实验环境可以让索引容量缩到零：

cdk deploy -c aoss_min_ocu=0

代价是：负载下熔断器会以 HTTP 429 丢弃批量写入，摄取重试会更频繁，且冷启动有延迟。摄取密集的环境保持非零下限（如默认的 2）。详见 external-docs/content/deploying.md 的 “OpenSearch Serverless (OCU) capacity configuration” 一节。

坑 2：Neptune 是固定成本的单实例

部署创建的是db.r8g.large（Graviton）单实例、无只读副本、7 天备份——这是持续的固定成本，而不是 Serverless 按量。注意两点：

• 先确认你的区域/可用区提供db.r8g.large实例类（真正的约束往往是可用性而非实例数配额）；
• dev 环境下该集群没有删除保护，make destroy-dev会不可逆地删掉整个图数据库。

坑 3：Bedrock token 才是吞吐和成本的天花板

本体归纳、文档富集、查询解析全部走 Bedrock，数据库扫描会“每张表调用一次 LLM”——大源的扫描成本和时间都由模型 token 决定，而不是 CPU。两个实用建议：

• 大源扫描撞 120 分钟截止时间失败时，先查每模型 TPM 限流，再考虑调大超时（SCL_DB_SCAN_ENRICHMENT_TIMEOUT_MINUTES）——被限流时多给时间没有用；
• 在 CloudWatch 的COA/Guardrails等命名空间和 Cost Explorer 里按ModelId维度观察消耗（监控细节见 external-docs/content/metrics.md）。

坑 4：资源随 namespace 数量线性增长

VKG 每个 namespace 跑一个 Fargate 服务（默认 1 vCPU/2GB），ENI、Cloud Map 注册、vCPU 配额消耗都随之线性增长。规划命名空间数量时，回头对照 Fargate vCPU 配额（默认 6）核算；本体规模大的 namespace 还可以按官方文档的 VKG Task Sizing 表调大 CPU/内存（调小则可能永远UNHEALTHY）。

及时止损：用对命令拆环境

make destroy-dev

务必用make destroy-dev而不是裸cdk destroy——AgentCore Runtime 的 ENI、VKG 的 ECS 服务、DataZone 域都不在 CloudFormation 的记录里，裸命令清不干净。还有一个反直觉的点：拆除通常比部署更慢，AgentCore 的 ENI 释放可能需要数小时甚至更久，属于 AWS 侧时序问题，耐心等待后重跑（步骤幂等）即可。

⚡ 避坑速查表

📚 延伸资料

• 完整部署文档（含区域前置条件、生产环境加固、故障排查）：external-docs/content/deploying.md
• 预检脚本源码（10 项检查逐项可读）：scripts/preflight-deploy.sh
• 部署脚本：scripts/deploy.sh、拆除脚本：scripts/destroy.sh
• 快速上手与日常开发：external-docs/content/getting-started.md
• 运行时监控指标：external-docs/content/metrics.md

一句话总结：先make preflight看配额，x86 机器先装 ARM64 模拟，部署时记住 us-east-1 双区域 bootstrap，运行期盯住 OpenSearch OCU 与 Bedrock token 这两项账单大头——把这四件事做在前面，部署之路基本畅通。