# AI-Agent-Container **Repository Path**: OpenCloudOS/ai-agent-container ## Basic Information - **Project Name**: AI-Agent-Container - **Description**: 本仓库用于社区贡献者提交基于 OpenCloudOS 9 的 AI / AI Agent 容器镜像。您可以挑选感兴趣的项目，为其编写基于 OpenCloudOS 9 的 Dockerfile 和容器镜像，并通过 PR 提交适配成果。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 19 - **Created**: 2026-03-31 - **Last Updated**: 2026-04-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# 🚀 OC9 AI 容器镜像共建 **OpenCloudOS 9 × 主流 AI/AI Agent 框架容器镜像适配仓库** [![OpenCloudOS](https://img.shields.io/badge/OpenCloudOS-9-blue?style=flat-square)](https://www.opencloudos.org/) [![License](https://img.shields.io/badge/License-Apache_2.0-green?style=flat-square)](./LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](https://gitee.com/OpenCloudOS/ai-agent-container/pulls) [![Gitee](https://img.shields.io/badge/Gitee-ai--agent--container-red?style=flat-square&logo=gitee)](https://gitee.com/OpenCloudOS/ai-agent-container)
--- >本仓库用于社区贡献者提交**基于 OpenCloudOS 9 的 AI / AI Agent 容器镜像**。您可以挑选感兴趣的项目，为其编写基于 OpenCloudOS 9 的 Dockerfile 和容器镜像，并通过 PR 提交适配成果。 > ## 📖 目录 - [参与贡献前必读](#参与贡献前必读) - [仓库结构](#仓库结构) - [贡献流程](#贡献流程) - [自动化 CI/CD 流水线](#自动化-cicd-流水线) - [适配框架清单](#适配框架清单) ## 参与贡献前必读 ### 环境要求 | 项目 | 要求 | |------|------| | 构建工具 | Docker（≥ 20.10）或 Buildah / Podman | | Python | ≥ 3.11（推荐 3.11） | | CUDA | 推荐 12.8（GPU 场景，非 GPU 可忽略） | | 硬件 | CPU 镜像无特殊要求；GPU 镜像需 NVIDIA GPU | ### Dockerfile 规范 不同类型的框架使用不同的基础镜像： | 场景 | 基础镜像 | 适用框架 | |------|---------|---------| | **纯 Python / CPU** | `opencloudos/opencloudos9-minimal:latest` | LangChain、CrewAI、Dify、FastGPT 等 | | **需要 GPU / CUDA** | `opencloudos/opencloudos9-cuda-devel:12.8` | vLLM、DeepSpeed、TensorRT-LLM、PyTorch 等 | > 详细硬件要求和 Dockerfile 规范请阅读 👉 [CONTRIBUTING.md](./CONTRIBUTING.md) ## 仓库结构 ``` ai-agent-container/ ├── README.md # 本文件 ├── CONTRIBUTING.md # 贡献指南（详细版） ├── FRAMEWORKS.md # 可适配的 AI 框架完整清单 ├── LICENSE ├── cuda_test.sh # GPU 基础环境检查参考模板 └── frameworks/ # 各框架适配目录（按 PR 提交） ├── vllm/ │ └── 0.10.2/ │ ├── Dockerfile │ ├── README.md │ ├── test.sh # 可选，基础功能验证脚本 │ └── build.conf # 可选，构建参数配置 ├── langchain/ │ └── 1.2.14/ │ └── ... └── ... ``` ## 贡献流程 > 详细规范请阅读 👉 [CONTRIBUTING.md](./CONTRIBUTING.md) ### 快速上手（4 步完成） **① Fork & Clone** ```bash git clone https://gitee.com/<你的用户名>/ai-agent-container.git cd ai-agent-container ``` **② 创建框架适配目录** ```bash mkdir -p frameworks/vllm/0.19.0 ``` **③ 编写 Dockerfile & 验证** ```bash # 构建镜像 docker build -t oc9-vllm:0.19.0 frameworks/vllm/0.19.0/ # 运行基础验证 docker run --rm --gpus all oc9-vllm:0.19.0 python3.11 -c "import vllm; print(vllm.__version__)" ``` **④ 提交 PR** ```bash git checkout -b feat/add-vllm git add frameworks/vllm/0.19.0/ git commit -m "feat: add vllm v0.19.0 container image for OC9" git push origin feat/add-vllm # 在 Gitee 上发起 Pull Request ``` ### PR 提交要求 每个 PR **必须包含**： | 文件 | 说明 | |------|------| | `frameworks/<框架名>/<版本号>/Dockerfile` | 基于 OC9 基础镜像（minimal、cuda-devel 或其他） | | `frameworks/<框架名>/<版本号>/README.md` | 框架简介、版本、构建命令、使用示例、已知问题 | 每个 PR **推荐包含**： | 文件 | 说明 | |------|------| | `frameworks/<框架名>/<版本号>/test.sh` | 基础功能验证脚本（宿主机运行，接收 `$1` 为镜像名:标签） | | `frameworks/<框架名>/<版本号>/build.conf` | 构建参数配置（镜像名、标签、是否需要 GPU 测试等） | ### 验收标准 - ✅ 基于 OpenCloudOS 9 基础镜像构建成功（`opencloudos9-minimal` `opencloudos9-cuda-devel` 或其他） - ✅ 可正常运行 - ✅ GPU 镜像需验证 CUDA 驱动兼容性（如适用） - ✅ Dockerfile 规范，无硬编码密钥或个人信息 - ✅ README 文档完备 - ✅ 包含 test.sh 和运行成功截图 ## 自动化 CI/CD 流水线 本仓库配有两条自动化流水线，贡献者提交 PR 后无需手动操作，流水线会自动完成检查与发布，并将结果以评论形式反馈到 PR。 ### 🔍 CI 门禁（PR 阶段） **触发时机**：PR 创建、更新（新 push）时自动触发；也可在 PR 评论中输入 `/retest` 手动重触发。 流水线仅检查**本次 PR 修改的目录**，分三个阶段依次执行： #### 阶段一：格式与配置校验 | 检查项 | 通过条件 | 失败影响 | |--------|---------|---------| | **必需文件** | 每个提交目录必须包含 `Dockerfile` 和 `README.md` | ❌ 阻断，PR 无法合并 | | **build.conf 必填** | `frameworks/<框架>/<版本>/` 三级目录**必须**提供 `build.conf`，否则无法推断镜像名 | ❌ 阻断 | | **IMAGE_NAME 格式** | 只允许小写字母、数字、`.`、`_`、`-`，且以字母或数字开头（`^[a-z0-9][a-z0-9._-]*$`） | ❌ 阻断 | | **IMAGE_TAG 格式** | 允许字母、数字、`.`、`_`、`-`，且以字母或数字开头（`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`） | ❌ 阻断 | | **BUILD_CONTEXT 格式** | 若声明，须符合 `key=路径` 格式 | ❌ 阻断 | | **GPU_TEST 合法值** | 只能是 `true` 或 `false` | ❌ 阻断 | | **Hadolint lint** | Dockerfile 最佳实践检查（忽略 DL3008/DL3013/DL3059） | ⚠ 警告，不阻断 | > **提前规避**：`build.conf` 字段说明与示例见 [CONTRIBUTING.md §2.2.1](./CONTRIBUTING.md)；常见 Hadolint 警告可在本地用 `hadolint Dockerfile` 提前检查。 #### 阶段二：构建验证 在 GPU 机器上执行 `docker build`，确认 Dockerfile 可以成功构建。 - 构建失败（语法错误、基础镜像拉取失败、依赖安装报错等）→ ❌ 阻断 #### 阶段三：功能测试 | 步骤 | 说明 | |------|------| | **基础测试** | 若提交了 `test.sh`，CI 会在 GPU 机器上执行 `bash test.sh <镜像名:标签>`，非零退出码即为失败 | | **GPU 测试** | `build.conf` 中声明 `GPU_TEST=true` 时，额外运行 `torch.cuda.is_available()` 验证 CUDA 可用性 | > **test.sh 编写规范**：脚本必须以第一个参数 `$1` 接收镜像名:标签，通过 `docker run --rm "$1" ...` 验证容器功能，验证通过 `exit 0`，失败 `exit 1`。详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 #### CI 结果反馈 PR 页面将收到评论通知，同时打上状态标签： | 结果 | 标签 | 说明 | |------|------|------| | 检查中 | `ci_running` | 流水线运行中 | | 全部通过 | `ci_passed` | 可以申请合并 | | 存在失败 | `ci_failed` | 请查看评论中的日志链接，修复后重新 push 或评论 `/retest` | --- ### 🚀 Publish 发布（合并后） **触发时机**：PR 被合并到 `master` 后自动触发。 流水线执行以下操作： 1. **重新构建**本次合并引入的镜像 2. **推送**到 Docker Hub（命名空间 `ocpub`），镜像名和 tag 来自 `build.conf` 中的 `IMAGE_NAME` 和 `IMAGE_TAG` 3. **防覆盖保护**：若该 tag 在 Docker Hub 上已存在，跳过推送并在日志中告警 > **注意**：若 PR 合并时该 tag 已在 Docker Hub 存在（如之前有同名同版本发布），镜像**不会**被覆盖。如需重新发布，请联系管理员手动删除 Docker Hub 上的对应 tag。 发布结果同样以 PR 评论反馈，包含已发布的完整镜像列表（`docker.io/ocpub/:`）。 --- ## 适配框架清单 > 完整清单（含各版本号、开源地址）请查看 👉 **[FRAMEWORKS.md](./FRAMEWORKS.md)** ### 如何选择？ - **新手推荐**：从 LangChain、ChromaDB、Open WebUI 等纯 Python 项目入手 - **进阶推荐**：vLLM、Dify、CrewAI 等核心生态项目 - **高挑战**：DeepSpeed、Megatron-LM、TensorRT-LLM 等 GPU 优化项目 ## 联系我们 - **Issue 反馈**：[提交 Issue](https://gitee.com/OpenCloudOS/ai-agent-container/issues) - **交流群**：有问题欢迎加群交流 TBD ## 许可证 本项目采用 [Apache License 2.0](./LICENSE) 许可证。