开发

开发#

源代码开发#

从源代码构建#

构建所有二进制文件

make build

构建特定组件

# Build controller
make build-controller-manager

# Build gateway plugins
make build-gateway-plugins

# Build metadata service
make build-metadata-service

代码生成#

修改 API 或自定义资源后

# Generate CRDs, RBAC, and webhook configurations
make manifests-all

# Generate DeepCopy methods and client code
make generate

代码质量#

运行 linter 检查代码风格并发现问题

# Run golangci-lint linter
make lint

# Run golangci-lint with auto-fixes
make lint-fix

测试框架#

AIBrix 包含一个全面的测试套件，包括单元测试、集成测试和端到端测试。

开发工作流程#

  1. 首先编写测试 - 为新功能添加单元/集成测试

  2. 本地运行 - 使用 make test 和 make test-integration

  3. E2E 验证 - 在提交更改前运行 make test-e2e

单元测试#

单元测试与源代码位于同一位置（*_test.go 文件）

# Run all unit tests with coverage
make test

# Run tests for specific package. e.g. lora controller
go test ./pkg/controller/modeladapter...

集成测试#

集成测试使用 Ginkgo 框架测试组件交互

# Run all integration tests
make test-integration

# Run specific integration tests
make test-integration-controller
make test-integration-webhook

端到端测试#

E2E 测试针对正在运行的 Kubernetes 集群验证完整的 AIBrix 功能。

开发环境（本地测试）

对于集群和 AIBrix 已在运行的本地开发

开发模式的先决条件

  • Kubernetes 集群正在运行且可访问

  • AIBrix 已部署且运行正常

# Development mode - run tests against existing setup
# make sure env KUBECONFIG is set correctly
make test-e2e

# Or run script directly
# Note: Required port-forwards should be active in this mode
go test ./test/e2e/ -v -timeout 0

CI 环境（自动化测试）

对于需要完整集群设置和拆除的 CI 管道

# Full CI setup - creates Kind cluster and installs AIBrix
KIND_E2E=true INSTALL_AIBRIX=true make test-e2e

# Or run script directly
./test/run-e2e-tests.sh

环境变量：- KIND_E2E=true - 使用正确的配置创建 Kind 集群 - INSTALL_AIBRIX=true - 构建镜像、安装依赖项并部署 AIBrix - SKIP_KUBECTL_INSTALL=true - 跳过 kubectl 安装（默认值：true） - SKIP_KIND_INSTALL=true - 跳过 Kind 安装（默认值：true）

容器镜像和部署#

构建容器镜像#

我们鼓励贡献者在大多数情况下在本地开发环境中构建和测试 AIBrix。如果您使用 Macbook，Docker Desktop 是最方便的工具。

构建 nightly docker 镜像

make docker-build-all

# build specific images
make docker-build-controller-manager

快速部署到开发环境#

运行以下命令将最新的代码更改快速部署到您的开发 kubernetes 环境中

kubectl apply -k config/dependency --server-side
kubectl apply -k config/default

如果您想清理所有内容并重新安装最新代码

kubectl delete -k config/default
kubectl delete -k config/dependency

使用 Kind 进行完整的开发设置#

对于带有监控的完整本地开发环境

# Complete AIBrix installation in Kind cluster
make dev-install-in-kind

# Start port forwarding for development services
make dev-port-forward

# Stop port forwarding
make dev-stop-port-forward

# Clean removal from Kind cluster
make dev-uninstall-from-kind

使用仅限 CPU 的 vLLM 进行手动测试#

本节解释了如何在仅限 CPU 的环境（例如，适用于 macOS 或 Linux 开发）中使用 vLLM 在本地 Kubernetes 集群中手动测试 AIBrix。

设置本地环境#

使用 Hugging Face CLI 在本地下载模型

huggingface-cli download facebook/opt-125m

使用 kind 启动本地集群（编辑 kind-config.yaml 以挂载您的模型缓存）

kind create cluster --config=./development/vllm/kind-config.yaml

构建并加载镜像

make docker-build-all
kind load docker-image aibrix/runtime:nightly

为您的平台加载 CPU 环境镜像

对于 macOS

docker pull aibrix/vllm-cpu-env:macos
kind load docker-image aibrix/vllm-cpu-env:macos

对于 Linux

docker pull aibrix/vllm-cpu-env:linux-amd64
kind load docker-image aibrix/vllm-cpu-env:linux-amd64

部署和测试 vLLM 模型#

在 kind 集群中部署 vLLM 模型

对于 macOS

kubectl create -k development/vllm/macos

对于 Linux

kubectl create -k development/vllm/linux

访问模型端点

kubectl port-forward svc/facebook-opt-125m 8000:8000 &

本地查询

curl -v https://:8000/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-key-1234567890" \
  -d '{
     "model": "facebook-opt-125m",
     "prompt": "Say this is a test",
     "temperature": 0.5,
     "max_tokens": 512
   }'

实用说明#

  • vllm-cpu-env 是开发和调试的理想选择。由于仅限 CPU 后端，推理延迟会很高。

  • 请务必挂载您的 Hugging Face 模型缓存目录，否则容器将在线重新下载。

  • 确认 runtime 和 env 镜像都已加载到 kind 中。

  • 使用 kubectl logs 或 kubectl exec 调试模型 pod 问题。

调试#

调试网关 IP#

kubectl get svc -n envoy-gateway-system

NAME                                     TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                   AGE
envoy-aibrix-system-aibrix-eg-903790dc   LoadBalancer   10.96.239.246   101.18.0.4    80:32079/TCP                              10d

另请遵循调试指南。

模拟 CPU 应用#

为了在开发环境中运行控制平面和数据平面 e2e，我们构建了一个模拟应用来模拟模型服务器。现在，它支持基本的模型推理、指标和 lora 功能。欢迎丰富这些功能。有关更多详细信息，请查看 development 文件夹。

GPU 测试环境#

如果您需要在真实的 GPU 环境中测试模型，我们强烈推荐 Lambda Labs 平台来安装和测试基于 kind 的部署。

注意

Kind 本身尚不支持 GPU。为了使用支持 GPU 的 kind 版本，请随时查看 nvkind。