尧图网站建设 
Knowhere生产部署完整教程Docker Compose自托管到AWS ECS上云实战指南【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhereKnowhere 是一个文档解析与检索系统它把 PDF、Word、PPT 等复杂文件转化为可供 AI Agent 和 RAG 应用使用的结构化文档记忆。本文将带你走完整条生产部署路径先用 Docker Compose 搭建本地基础设施并验证自托管运行再基于仓库内置的模板把 Knowhere API 和 Worker 服务发布到 AWS ECS Fargate覆盖密钥管理、资源规格配置、镜像构建与部署后验证等关键步骤。Knowhere 部署架构速览先搞懂 3 类核心组件在动手部署前先理解 Knowhere 由哪些部分组成这样后续每一步配置才有章可循 API 服务对外提供 HTTP 接口默认端口5005负责作业提交、检索、账单与 Webhook健康检查入口为/healthWorker 服务基于 Celery 的异步任务执行器承担文档解析、记忆构建等重活基础设施PostgreSQL业务数据、Redis缓存与任务队列、对象存储本地用 LocalStack 模拟 S3生产用真实 S3Knowhere 2.0 的解析流水线采用视觉轨道 文本轨道双轨设计两条轨道最终汇入同一套可导航的记忆 Schema——这也是为什么 Worker 需要足够 CPU/内存来处理复杂文档部署后任意 Agent 都可以通过同一套工具契约检索 Knowhere 记忆并返回带引用出处的证据第一阶段Docker Compose 自托管部署一键启动本地基础设施仓库的 deploy/local-dev/ 目录内置了完整的 Compose 开发栈对应 docker-compose.dev.yml包含 Redis 7、PostgreSQL 15 和 LocalStack 三个服务并自带健康检查。从仓库根目录执行启动脚本即可cd deploy/local-dev ./start-dev.shstart-dev.sh 会自动完成三件事拉起 Compose 栈并等待 PostgreSQL、Redis、LocalStack 全部就绪校验各服务健康状态pg_isready/redis-cli ping/ LocalStack 健康接口打印服务端点和后续启动 API/Worker 的指引启动完成后三个本地端点如下表服务端点说明PostgreSQLlocalhost:5432账号root/root123库名KnowhereRedislocalhost:6379开启 AOF 持久化2GB 内存上限LocalStackhttp://localhost:4566模拟 S3/SNS/SQS免 AWS 账号停止栈只需执行同目录下的 stop-dev.sh它会智能识别docker-compose与docker compose两种环境。构建并验证 API / Worker 容器镜像生产镜像定义在 deploy/docker/ 下Dockerfile.api 采用多阶段构建先用uv sync --locked锁定依赖安装到 builder 阶段运行时镜像只拷贝虚拟环境与业务代码并以非 root 用户运行同时内置 30 秒间隔的/health健康检查——这些设计会原样带入 ECS 部署。在真正上云之前强烈建议先跑一次本地 Docker 冒烟测试。docker-runtime-smoke.sh 会创建隔离网络、启动一次性 PostgreSQL/Redis 容器、构建 API 与 Worker 镜像、执行 Alembic 迁移然后逐项验证两个服务的健康状态结束后自动清理./deploy/ecs/docker-runtime-smoke.sh该脚本使用文件系统对象存储与 mock LLM 响应不调用任何 AWS API适合在 CI 或部署前做最后一公里验证。⚠️ 注意LocalStack 社区版并不实现 ECS API无法用来验证 Fargate 编排本地验证请以上述冒烟脚本为准见 deploy/ecs/README.md。第二阶段上云 AWS ECS Fargate理解 ECS 任务定义模板deploy/ecs/ 目录存放共享knowhere-fargate集群的部署模板包含 API 与 Worker 两份 JSON 任务定义task-definition-api.staging.jsonAPI 容器暴露5005端口配置awslogs日志组、30 秒健康检查密钥全部通过 Secrets Manager 注入task-definition-worker.staging.jsonWorker 容器资源占用更高解析密集型模板刻意不包含S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY等长期凭证——S3_TYPEs3模式下 boto3 直接从 ECS 任务角色获取临时凭证安全性更好。渲染任务定义一条命令生成部署文件模板中的${...}占位符由渲染脚本 render_task_definitions.py 替换。核心原则必须使用不可变的 ECR 镜像摘要digest 精确的 IAM 角色与密钥 ARN渲染器在输入缺失、占位符未解析或出现长期 S3 凭证变量时都会直接报错API_IMAGE107424103509.dkr.ecr.us-east-1.amazonaws.com/knowhere/knowhere-backendsha256:... \ WORKER_IMAGE107424103509.dkr.ecr.us-east-1.amazonaws.com/knowhere/knowhere-workersha256:... \ EXECUTION_ROLE_ARNarn:aws:iam::...:role/knowhere-fargate-staging-execution-role \ API_TASK_ROLE_ARNarn:aws:iam::...:role/knowhere-api-staging-task-role \ WORKER_TASK_ROLE_ARNarn:aws:iam::...:role/knowhere-worker-staging-task-role \ SECRETS_ARNarn:aws:secretsmanager:us-east-1:...:secret:knowhere/staging/runtime-... \ DEPLOYMENT_ENVIRONMENTstaging \ API_CPU256 API_MEMORY1024 \ WORKER_CPU2048 WORKER_MEMORY4096 \ S3_BUCKET_NAMEknowhere-storage-staging \ python deploy/ecs/render_task_definitions.py --environment staging --output-dir /tmp/knowhere-ecs-rendered其中 Secrets Manager 密钥为 JSON 格式需包含DATABASE_URL、REDIS_HOST、CELERY_REDIS_URL、SECRET_KEY、各 LLM API Key、Stripe/QStash 密钥等完整清单见 deploy/ecs/README.md。资源规格staging 与 production 的差别环境API 规格Worker 规格Staging256 CPU / 1024 MiB2048 CPU / 4096 MiBProduction512 CPU / 2048 MiB2048 CPU / 4096 MiBWORKER_CONCURRENCY10生产发布工作流只针对指向main的正式 tag 触发先执行数据库迁移、再更新 ECS 服务且不会创建或删除任何 AWS 资源——ECS 服务、负载均衡目标、CloudWatch 日志组、ACM 证书等前置资源需由运维预先创建并验证。部署后必做检索索引回填与验证发布不是终点。含新增迁移的版本上线后存量文档的检索统计需要一次性回填。请以一次性容器方式运行新部署的 API 镜像不要放进长期运行的 API 任务里# 只读检查统计库存 python /app/scripts/backfill_map_unit_statistics.py --check --batch-size 100 # 可选先对单篇文档做金丝雀回填 python /app/scripts/backfill_map_unit_statistics.py --document-id document-id --apply --batch-size 100 # 全量回填后做最终就绪检查 python /app/scripts/backfill_map_unit_indexes.py --check脚本按文档修订独立提交、可安全重跑建议先验证金丝雀检索效果再全量执行且同一时间只运行一个维护进程。完整的维护窗口、就绪门禁与回滚流程请参考 retrieval-serving-index-rollout-runbook.md。常见问题 FAQQ本地起不来服务怎么排查先看docker compose logs中三个基础设施容器的健康检查再确认 API 的/healthcurl http://localhost:5005/health与 OpenAPI 文档页http://localhost:5005/docs是否可达。QWorker 数量需要多少生产参考规格为 2 vCPU / 4 GiB 单实例配 10 并发staging 手动运维工作流默认启动 2 个健康 Worker 后再启动 1 个 API。Q如何低成本停掉 staging 省钱官方工作流提供手动start/stop/status操作stop会等待 30 分钟 Worker 排空窗口再停止服务需负责人审批引用。总结一条清晰的 Knowhere 生产部署路径就是Docker Compose 拉起基础设施 → 冒烟脚本验证镜像 → 模板渲染 ECS 任务定义 → 发布并回填检索索引 → 验证健康检查与检索就绪。仓库内 deploy/ 目录下的每个文件Compose 栈、Dockerfile、ECS 模板与渲染器都可直接复用按本文顺序执行你就能把 Knowhere 从本地自托管平滑推进到云上生产环境 【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Knowhere生产部署完整教程：Docker Compose自托管到AWS ECS上云实战指南
Knowhere生产部署完整教程Docker Compose自托管到AWS ECS上云实战指南【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhereKnowhere 是一个文档解析与检索系统它把 PDF、Word、PPT 等复杂文件转化为可供 AI Agent 和 RAG 应用使用的结构化文档记忆。本文将带你走完整条生产部署路径先用 Docker Compose 搭建本地基础设施并验证自托管运行再基于仓库内置的模板把 Knowhere API 和 Worker 服务发布到 AWS ECS Fargate覆盖密钥管理、资源规格配置、镜像构建与部署后验证等关键步骤。Knowhere 部署架构速览先搞懂 3 类核心组件在动手部署前先理解 Knowhere 由哪些部分组成这样后续每一步配置才有章可循 API 服务对外提供 HTTP 接口默认端口5005负责作业提交、检索、账单与 Webhook健康检查入口为/healthWorker 服务基于 Celery 的异步任务执行器承担文档解析、记忆构建等重活基础设施PostgreSQL业务数据、Redis缓存与任务队列、对象存储本地用 LocalStack 模拟 S3生产用真实 S3Knowhere 2.0 的解析流水线采用视觉轨道 文本轨道双轨设计两条轨道最终汇入同一套可导航的记忆 Schema——这也是为什么 Worker 需要足够 CPU/内存来处理复杂文档部署后任意 Agent 都可以通过同一套工具契约检索 Knowhere 记忆并返回带引用出处的证据第一阶段Docker Compose 自托管部署一键启动本地基础设施仓库的 deploy/local-dev/ 目录内置了完整的 Compose 开发栈对应 docker-compose.dev.yml包含 Redis 7、PostgreSQL 15 和 LocalStack 三个服务并自带健康检查。从仓库根目录执行启动脚本即可cd deploy/local-dev ./start-dev.shstart-dev.sh 会自动完成三件事拉起 Compose 栈并等待 PostgreSQL、Redis、LocalStack 全部就绪校验各服务健康状态pg_isready/redis-cli ping/ LocalStack 健康接口打印服务端点和后续启动 API/Worker 的指引启动完成后三个本地端点如下表服务端点说明PostgreSQLlocalhost:5432账号root/root123库名KnowhereRedislocalhost:6379开启 AOF 持久化2GB 内存上限LocalStackhttp://localhost:4566模拟 S3/SNS/SQS免 AWS 账号停止栈只需执行同目录下的 stop-dev.sh它会智能识别docker-compose与docker compose两种环境。构建并验证 API / Worker 容器镜像生产镜像定义在 deploy/docker/ 下Dockerfile.api 采用多阶段构建先用uv sync --locked锁定依赖安装到 builder 阶段运行时镜像只拷贝虚拟环境与业务代码并以非 root 用户运行同时内置 30 秒间隔的/health健康检查——这些设计会原样带入 ECS 部署。在真正上云之前强烈建议先跑一次本地 Docker 冒烟测试。docker-runtime-smoke.sh 会创建隔离网络、启动一次性 PostgreSQL/Redis 容器、构建 API 与 Worker 镜像、执行 Alembic 迁移然后逐项验证两个服务的健康状态结束后自动清理./deploy/ecs/docker-runtime-smoke.sh该脚本使用文件系统对象存储与 mock LLM 响应不调用任何 AWS API适合在 CI 或部署前做最后一公里验证。⚠️ 注意LocalStack 社区版并不实现 ECS API无法用来验证 Fargate 编排本地验证请以上述冒烟脚本为准见 deploy/ecs/README.md。第二阶段上云 AWS ECS Fargate理解 ECS 任务定义模板deploy/ecs/ 目录存放共享knowhere-fargate集群的部署模板包含 API 与 Worker 两份 JSON 任务定义task-definition-api.staging.jsonAPI 容器暴露5005端口配置awslogs日志组、30 秒健康检查密钥全部通过 Secrets Manager 注入task-definition-worker.staging.jsonWorker 容器资源占用更高解析密集型模板刻意不包含S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY等长期凭证——S3_TYPEs3模式下 boto3 直接从 ECS 任务角色获取临时凭证安全性更好。渲染任务定义一条命令生成部署文件模板中的${...}占位符由渲染脚本 render_task_definitions.py 替换。核心原则必须使用不可变的 ECR 镜像摘要digest 精确的 IAM 角色与密钥 ARN渲染器在输入缺失、占位符未解析或出现长期 S3 凭证变量时都会直接报错API_IMAGE107424103509.dkr.ecr.us-east-1.amazonaws.com/knowhere/knowhere-backendsha256:... \ WORKER_IMAGE107424103509.dkr.ecr.us-east-1.amazonaws.com/knowhere/knowhere-workersha256:... \ EXECUTION_ROLE_ARNarn:aws:iam::...:role/knowhere-fargate-staging-execution-role \ API_TASK_ROLE_ARNarn:aws:iam::...:role/knowhere-api-staging-task-role \ WORKER_TASK_ROLE_ARNarn:aws:iam::...:role/knowhere-worker-staging-task-role \ SECRETS_ARNarn:aws:secretsmanager:us-east-1:...:secret:knowhere/staging/runtime-... \ DEPLOYMENT_ENVIRONMENTstaging \ API_CPU256 API_MEMORY1024 \ WORKER_CPU2048 WORKER_MEMORY4096 \ S3_BUCKET_NAMEknowhere-storage-staging \ python deploy/ecs/render_task_definitions.py --environment staging --output-dir /tmp/knowhere-ecs-rendered其中 Secrets Manager 密钥为 JSON 格式需包含DATABASE_URL、REDIS_HOST、CELERY_REDIS_URL、SECRET_KEY、各 LLM API Key、Stripe/QStash 密钥等完整清单见 deploy/ecs/README.md。资源规格staging 与 production 的差别环境API 规格Worker 规格Staging256 CPU / 1024 MiB2048 CPU / 4096 MiBProduction512 CPU / 2048 MiB2048 CPU / 4096 MiBWORKER_CONCURRENCY10生产发布工作流只针对指向main的正式 tag 触发先执行数据库迁移、再更新 ECS 服务且不会创建或删除任何 AWS 资源——ECS 服务、负载均衡目标、CloudWatch 日志组、ACM 证书等前置资源需由运维预先创建并验证。部署后必做检索索引回填与验证发布不是终点。含新增迁移的版本上线后存量文档的检索统计需要一次性回填。请以一次性容器方式运行新部署的 API 镜像不要放进长期运行的 API 任务里# 只读检查统计库存 python /app/scripts/backfill_map_unit_statistics.py --check --batch-size 100 # 可选先对单篇文档做金丝雀回填 python /app/scripts/backfill_map_unit_statistics.py --document-id document-id --apply --batch-size 100 # 全量回填后做最终就绪检查 python /app/scripts/backfill_map_unit_indexes.py --check脚本按文档修订独立提交、可安全重跑建议先验证金丝雀检索效果再全量执行且同一时间只运行一个维护进程。完整的维护窗口、就绪门禁与回滚流程请参考 retrieval-serving-index-rollout-runbook.md。常见问题 FAQQ本地起不来服务怎么排查先看docker compose logs中三个基础设施容器的健康检查再确认 API 的/healthcurl http://localhost:5005/health与 OpenAPI 文档页http://localhost:5005/docs是否可达。QWorker 数量需要多少生产参考规格为 2 vCPU / 4 GiB 单实例配 10 并发staging 手动运维工作流默认启动 2 个健康 Worker 后再启动 1 个 API。Q如何低成本停掉 staging 省钱官方工作流提供手动start/stop/status操作stop会等待 30 分钟 Worker 排空窗口再停止服务需负责人审批引用。总结一条清晰的 Knowhere 生产部署路径就是Docker Compose 拉起基础设施 → 冒烟脚本验证镜像 → 模板渲染 ECS 任务定义 → 发布并回填检索索引 → 验证健康检查与检索就绪。仓库内 deploy/ 目录下的每个文件Compose 栈、Dockerfile、ECS 模板与渲染器都可直接复用按本文顺序执行你就能把 Knowhere 从本地自托管平滑推进到云上生产环境 【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考