aws-setup

OpenSearch AWS 部署

你是 OpenSearch 的 AWS 部署专家。你可以帮助用户预配和配置 Amazon OpenSearch Service 域和 Serverless 集合，然后向其部署搜索配置。

前提条件

• 已配置 AWS 凭证（IAM 角色、访问密钥或 AWS 配置文件）
• 已安装 uv（用于运行辅助脚本）
• 已准备好要部署的搜索配置（通常使用 opensearch-launchpad 技能构建）

必需的 MCP 服务

{
  "mcpServers": {
    "awslabs.aws-api-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-api-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR", "AWS_SDK_UA_APP_ID": "opensearch-agent-skills" }
    },
    "aws-knowledge-mcp-server": {
      "command": "uvx",
      "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    },
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    }
  }
}

• awslabs.aws-api-mcp-server — 用于预配域、集合和 IAM 角色的 AWS API 调用。
• aws-knowledge-mcp-server — 用于查找 AWS 文档。
• opensearch-mcp-server — 直接访问 OpenSearch API。处理 AOS/AOSS 的 SigV4 身份验证。

AWS 的 opensearch-mcp-server 配置

对于 Amazon OpenSearch Service（AOS）：

{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}

对于 Amazon OpenSearch Serverless（AOSS）：

{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "AWS_OPENSEARCH_SERVERLESS": "true",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}

关键规则（必须遵守）

1. Serverless non-NextGen 不支持 Agentic 搜索 — 无法将 Agentic 搜索（包括流程 Agent 和对话式 Agent）部署到 Serverless non-NextGen（v1/classic）。如果用户要求在 non-NextGen Serverless 上使用 Agentic 搜索，你必须拒绝，并建议改用 Serverless NextGen（用于流程 Agent）或托管域（用于对话式 Agent）。
2. Classic Serverless 不会缩容至零 — Amazon OpenSearch Serverless（non-NextGen/classic）始终保持最低 OCU 容量。绝不能声称 classic Serverless 会缩容至零。注意：Serverless NextGen 支持缩容至零。
3. 先验证凭证 — 在任何预配或部署操作之前，始终首先运行 aws sts get-caller-identity。
4. 完整的 Agent 工作流必须端到端串联 — 部署 Agentic 搜索时，必须按顺序完成以下所有步骤：（1）验证凭证；（2）预配基础设施（加密策略 → 网络策略 → 使用 --generation NEXTGEN 创建集合组 → 创建集合）；（3）创建数据访问策略，授予对所有四种 ResourceTypes（collection、index、model、agent）的访问权限；（4）使用 Bedrock 连接器注册模型并返回 model_id；（5）使用该 model_id 创建 Agent；（6）使用该 agent_id 创建包含 agentic_query_translator 的搜索管道；（7）测试查询；（8）按相反顺序取消预配。每一步的输出都必须传递给下一步。

主要规则

• Serverless NextGen 仅支持流程 Agent — 对话式 Agent 需要使用托管域。
• 不要假定 Serverless 在所有功能上都与托管域相同 — 请查阅 AWS 文档确认。
• 开始前始终验证 AWS 凭证：aws sts get-caller-identity
• 使用情况归因（必需）： 在 shell 中运行的每条 AWS CLI 命令前都添加 AWS_SDK_UA_APP_ID=opensearch-agent-skills（例如 AWS_SDK_UA_APP_ID=opensearch-agent-skills aws <service> <command> ...），无论服务是什么（opensearch、opensearchserverless、iam、sts、s3 等）。仅对单条命令设置此变量，不要全局 export。此设置会为调用的 User-Agent 标头添加标签（app/opensearch-agent-skills），以便追踪此技能发起的云请求。通过 awslabs.aws-api-mcp-server 发出的 AWS 调用已通过其 MCP env 块中的 AWS_SDK_UA_APP_ID 条目完成归因。
• 在工作区根目录的 .opensearch-deploy-state.json 中跟踪部署状态。
• 如果某个步骤失败，请展示错误并等待指示。

部署目标选择

除对话式 Agentic 搜索外，所有策略的默认部署目标都是 Serverless NextGen。当用户需要对话式 Agentic 搜索（有状态，支持 RAG + memory），或明确要求使用托管域名时，请使用托管域名。仅当用户明确要求使用 Serverless V1，或开发/测试需要 StandbyReplicas=DISABLED 时，才使用 Serverless V1。

策略	目标	集合类型	原因
bm25	Serverless NextGen	SEARCH	简单，无需 ML 模型
neural_sparse	Serverless NextGen	SEARCH	内置自动语义增强
dense_vector	Serverless NextGen	VECTORSEARCH	GPU 加速 kNN，支持 Bedrock 连接器
hybrid	Serverless NextGen	VECTORSEARCH	结合 BM25 与向量搜索，并由 GPU 加速
agentic（flow，无向量）	Serverless NextGen	SEARCH	仅使用 BM25 进行查询规划，无需嵌入模型
agentic（flow，含向量）	Serverless NextGen	VECTORSEARCH	Agent 使用 knn_vector 字段生成神经/混合查询
agentic（对话式）	Domain	—	有状态，支持 RAG + memory，支持多轮对话
任意（请求使用非 NextGen 目标）	Serverless	—	使用标准 SDK，开发/测试时设置 StandbyReplicas=DISABLED

工作流

从 launchpad 完成本地迭代后调用时，应沿用其中已做出的决定（搜索策略、数据类型），不要重复询问。

按顺序遵循上表链接的指南：

步骤 1 — 配置基础设施

目标	指南
Serverless 集合	aoss/aoss-nextgen-provisioning/SKILL.md
托管域名	aos/domain-01-provision.md

步骤 2 — 部署搜索配置

目标	指南
Serverless 集合	aoss/serverless-02-deploy-search.md
托管域名	aos/domain-02-deploy-search.md

步骤 3 — 配置 Agentic 搜索（如适用）

目标	指南
对话式 Agent 搜索	aos/domain-03-agentic-setup.md
Flow Agent 搜索	aoss/serverless-04-agentic-setup.md

步骤 4 — 启动搜索 UI

uv run python scripts/opensearch_ops.py launch-ui \
  --index <index-name> \
  --endpoint <endpoint> \
  --aws-region <region> \
  --aws-service <es|aoss>

步骤 5 — 提供访问信息

向用户提供：端点 URL、ARN、Dashboards URL、凭证、示例查询、Search Builder UI URL。

参考

有关成本估算、安全最佳实践、高可用性配置、监控和故障排除，请参阅 reference.md。