Giới thiệu

Tích hợp một tính năng AI mới vào một kho microservices polyglot không phải là điều khó khăn. Trong bài viết này, tôi sẽ hướng dẫn bạn cách tích hợp dịch vụ Nano Banana Try-On (tryonservice/) vào demo phong cách Google Online Boutique: container hóa dịch vụ Python gRPC, triển khai trên Kubernetes, kết nối frontend bằng Go, và kích hoạt quy trình làm việc địa phương/phát triển với Skaffold và Docker Compose.

Những nội dung sẽ được đề cập

• Thiết kế dịch vụ và bề mặt gRPC
• Container hóa (Dockerfile đa giai đoạn)
• Triển khai và dịch vụ Kubernetes và cấu hình biến môi trường
• Tích hợp frontend (Go) qua biến môi trường + client gRPC
• Phát triển địa phương với Skaffold và Docker Compose
• Các móc quan sát với OpenTelemetry

Kiến trúc tổng quan

Dịch vụ mới tryonservice là một dịch vụ Python gRPC tạo ra hình ảnh thử đồ ảo cho người dùng và sản phẩm đã cho. Frontend Go sẽ cung cấp các route HTTP và gọi tryonservice qua gRPC. Mọi thứ được triển khai trên Kubernetes; hình ảnh được xây dựng thông qua Skaffold.

Dịch vụ Try-On (Python + gRPC)

Điểm vào chính: src/tryonservice/tryon_server.py

• Máy chủ gRPC triển khai TryOnService với hai RPC: TryOnProduct và GetTryOnHistory.
• Sử dụng Google Gemini qua google-genai khi có GEMINI_API_KEY; ngược lại sẽ trả về một hình ảnh giả để quy trình phát triển diễn ra suôn sẻ.
• Phát sinh nhật ký có cấu trúc và các trace OpenTelemetry tùy chọn.

Điểm nổi bật trong mã

class TryOnService(demo_pb2_grpc.TryOnServiceServicer):
    def TryOnProduct(self, request, context):
        # Xử lý yêu cầu thử đồ
        pass

def serve():
    port = os.environ.get('PORT', '5012')
    server.add_insecure_port(f'[::]:{port}')
    logger.info(f'TryOn service listening on port {port}')

Khả năng quan sát

Khả năng quan sát là tùy chọn thông qua OTLP:

if os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT'):
    resource = Resource(attributes={"service.name": "tryonservice"})

Phụ thuộc

Các phụ thuộc được chỉ định trong requirements.txt:

grpcio==1.68.1
google-genai==0.3.0
Pillow==11.0.0
opentelemetry-api==1.29.0
opentelemetry-exporter-otlp==1.29.0

Container hóa (Dockerfile đa giai đoạn)

Dịch vụ sử dụng một build hai giai đoạn để giữ cho hình ảnh runtime mỏng, mở gRPC trên cổng 5012 và chạy máy chủ Python trực tiếp.

FROM python:3.12-slim AS base
COPY requirements.txt .
RUN pip install --prefix="/install" -r requirements.txt
WORKDIR /tryonservice
EXPOSE 5012
ENTRYPOINT ["python", "tryon_server.py"]

Kubernetes: Triển khai và Dịch vụ

Chúng ta khai báo Triển khai và Dịch vụ ClusterIP, và cấu hình các biến môi trường cho cổng, khóa Gemini (dưới dạng Secret), và OTEL exporter. Các probe là kiểm tra TCP đơn giản trên cổng gRPC.

apiVersion: apps/v1
  name: tryonservice
  containers:
    image: gcr.io/quiet-cider-472416-a5/tryonservice:v2
    env:
      - name: PORT
        value: "5012"
      - name: GEMINI_API_KEY
        secretKeyRef:
          name: gemini-api-key
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: "otel-collector:4317"

Skaffold: xây dựng và triển khai

Skaffold theo dõi và xây dựng hình ảnh dịch vụ và triển khai manifests qua kustomize.

- image: tryonservice
  context: src/tryonservice
  kustomize:
    - kubernetes-manifests

Điều này có nghĩa là skaffold dev hoặc skaffold run sẽ xây dựng src/tryonservice và triển khai cùng với các dịch vụ khác.

Kết nối Frontend (Go)

Frontend Go tiêu thụ TRYON_SERVICE_ADDR và mở một kết nối gRPC; các route /tryon và /tryon/history chuyển tiếp các hành động của người dùng tới dịch vụ.

tryOnSvcAddr string
mustMapEnv(&svc.tryOnSvcAddr, "TRYON_SERVICE_ADDR")
mustConnGRPC(ctx, &svc.tryOnSvcConn, svc.tryOnSvcAddr)
r.HandleFunc(baseUrl + "/tryon", svc.tryOnHandler).Methods(http.MethodPost)
r.HandleFunc(baseUrl + "/tryon/history", svc.tryOnHistoryHandler).Methods(http.MethodGet)

Trong Kubernetes, frontend nhận biến môi trường từ manifest Triển khai của nó:

- name: TRYON_SERVICE_ADDR
  value: "tryonservice:5012"

Chạy cục bộ với Skaffold

Yêu cầu trước

• Docker, kubectl, một cụm Kubernetes cục bộ hoặc từ xa, và Skaffold.

Tạo Secret cho khóa API Gemini (tùy chọn)

kubectl create secret generic gemini-api-key \
  --from-literal=key="$GEMINI_API_KEY"

Khởi động vòng lặp phát triển

skaffold dev

Chuyển tiếp cổng dịch vụ thử đồ cho các thử nghiệm gRPC nhanh

kubectl port-forward deployment/tryonservice 5012:5012

Ví dụ kiểm tra gRPC với grpcurl

grpcurl -plaintext localhost:5012 list

Chạy với Docker Compose

Nếu bạn thích Compose để chạy nhanh toàn bộ hệ thống:

docker compose up --build

Đảm bảo rằng các biến môi trường của frontend và dịch vụ thử đồ phù hợp; trong kho này, chúng được xác định trong docker-compose.yml.

Khả năng quan sát (tùy chọn)

Đặt OTEL_EXPORTER_OTLP_ENDPOINT trong tryonservice để phát sinh các trace đến bộ thu thập của bạn. Frontend đã được instrumented OTel qua otelgrpc và otelhttp.

Những điểm cần lưu ý và mẹo

• Nếu GEMINI_API_KEY không được thiết lập, dịch vụ sẽ quay lại hình ảnh giả. Điều này rất tốt cho các môi trường phát triển và CI.
• Các probe sẵn có và sống sót gRPC sử dụng kiểm tra TCP trên cổng 5012. Nếu bạn thêm TLS, hãy chuyển đổi các probe tương ứng.
• Giữ cho kích thước hình ảnh nhỏ bằng cách dựa vào Dockerfile hai giai đoạn và tránh các công cụ xây dựng không cần thiết trong hình ảnh runtime.

Kết luận

Đó là toàn bộ con đường tích hợp: dịch vụ microservice Python gRPC → container → Kubernetes → frontend Go → quy trình làm việc địa phương/phát triển với Skaffold và Compose → OTel tùy chọn. Bạn có thể áp dụng cùng một mẫu để thêm nhiều khả năng hỗ trợ AI vào demo.