歡迎來到 「 從0開始的MLFLOW應用搭建 」。
Hi 各位我是Josh，也是一名資料工作者，期待透過這次的分享把MLFLOW的知識內容整理起來與各位大大分享，可以把這次內容當作一個MLFlow搭建與使用的雛形整理，希望可以開箱即用，也方便後續做抽換或延伸。如果有甚麼不足的地方，歡迎各位大大多多回饋與交流，很榮幸可以與各位交流。
那我們就來開始本次的系列分享:

背景與目標（為什麼要做）

如果我們要做一個「企業級動畫推薦系統」，不能只算出推薦模型，還要可追蹤、可比較、可部署、可被前端使用，本次的分享將學習如何使用mlflow來執行模型生命週期，整體技術組合是 MLflow + FastAPI + Streamlit + AB Test，並以 Docker + docker-compose 管好所有服務，確保每台機器一鍵起來、彼此在同一網路上可互通。

名詞解釋

• MLflow：幫你「做實驗記錄」與「模型版本管理」的系統（參數、指標、模型檔、註冊表）。
• FastAPI：把模型包成 HTTP 服務的框架（例如 /recommend）。
• Streamlit：快速做互動網頁（使用者選 5 部動畫 → 顯示推薦）。
• AB Test：同一時間把流量分給不同模型，看誰的點擊/轉換更好。
• Docker / docker-compose：把每個服務放進容器，用一個檔案把多個容器一次啟動，彼此用同一個虛擬網路（今天我們用 mlops-net）。
• Docker Desktop：一個圖形化應用程式，幫你在 Windows 或 macOS 上「模擬 Linux 環境」來跑 Docker，幫次將完全使用Docker Desktop + VScode來進行。
• VS Code (Visual Studio Code)：一個跨平台的輕量級程式編輯器，知道大家都熟透了XD。

我們要用的資料（動畫推薦案例）

Kaggle 的 Anime Recommendations Database：

• animes.csv：動畫基本資訊（名稱、類型、描述、評分…）
• user_ratings.csv：使用者對動畫的評分
  重點：資料乾淨、規模適中，適合做 user-based、item-based 兩種推薦並比較。
• 這部分後續再介紹，今天先把環境建立起來

系統藍圖

[Kaggle 資料] → [清理/特徵] → [多模型訓練]
                          │
                    (MLflow Tracking/Artifacts/Registry)
                          │
      Streamlit UI  ←  FastAPI  →  /log-ab-event（AB 記錄）

今日實作目標

1. 建立專案資料夾
2. 用 docker-compose 啟動 Postgres（MLflow 後端）、MLflow 伺服器、Jupyter 開發容器
3. 確認容器在同一網路 mlops-net 可互通

1) 專案結構

本次示範會用 usr/ 路徑來建構資料夾與程式碼檔案，相關檔案歡迎使用以下的repo。

cd usr/
git clone https://github.com/JoshuaChen40/mlflow-fastapi-zero-to-prod.git

2) docker-compose.yml 內容

主要建立postgres當作資料庫、python-dev一個常駐的開發環境以及我們的核心Mflow容器負責提供追蹤模型的服務。隨著文章系列的展開，yaml內容會更動，請以上方repo裡面的為準。
另外，如果要自行使用並且會對外服務，要自行謹慎思考網路與權限(帳號、密碼、Token、環境變數)的管理，本系列僅以方便示範為方向，沒有做任何資安考量。

services:
  postgres:
    image: postgres:14
    container_name: postgres
    restart: always
    environment:
      POSTGRES_USER: mlflow
      POSTGRES_PASSWORD: mlflow
      POSTGRES_DB: mlflow
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - mlops-net

  mlflow:
    build:
      context: .
      dockerfile: docker/Dockerfile.mlflow
    container_name: mlflow
    depends_on:
      - postgres
    ports:
      - "5000:5000"
    environment:
      MLFLOW_BACKEND_STORE_URI: postgresql://mlflow:mlflow@postgres:5432/mlflow
      MLFLOW_ARTIFACT_ROOT: /mlflow/artifacts
    volumes:
      - ./workspace/mlruns:/mlflow/artifacts
    command: >
      mlflow server
      --backend-store-uri postgresql://mlflow:mlflow@postgres:5432/mlflow
      --default-artifact-root /mlflow/artifacts
      --host 0.0.0.0
      --port 5000
    networks:
      - mlops-net

  python-dev:
    build:
      context: .
      dockerfile: docker/Dockerfile.dev
    container_name: python-dev
    working_dir: /usr/mlflow
    volumes:
      - ./:/usr/mlflow
    ports:
      - "8888:8888"
    command: >
      jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token=Aa123456
    networks:
      - mlops-net

volumes:
  postgres_data:

networks:
  mlops-net:
    driver: bridge

• Postgres 資料庫
  • MLflow 會把模型的訓練紀錄（參數、指標、路徑）都存進去。
  • 設定了帳號密碼：mlflow / mlflow。
• MLflow 服務
  • 它會連到 Postgres 當後端資料庫，並把模型檔案存到 workspace/mlruns 資料夾。
  • 供一個網頁介面（http://localhost:5000）讓你查看和管理實驗結果。
• pyhon 開發環境（python-dev）
  • 可以把它想成一個雲端的「開發筆記本」。
  • 內建 Jupyter Lab，你打開瀏覽器就能寫程式碼和跑模型。
  • 對外開放在 http://localhost:8888，並用 Aa123456 當密碼（token）。

3) 一鍵啟動與驗證

# 第一次建置
docker compose up -d --build

# 看容器是否正常
docker compose ps

# 看網路（確認三個服務都在 mlops-net）
docker network inspect anime-recommender_mlops-net

打開：

• MLflow UI：http://localhost:5000
• JupyterLab：http://localhost:8888（Token：Aa123456）

連線 Postgres（例如 DBeaver）：
Host localhost、Port 5432、DB mlflow、User mlflow、Password mlflow
（容器內互連請用 服務名 postgres 當主機名，因為同網路上會自動做 DNS 解析）

5) 今天先小試牛刀（把一個假實驗寫進 MLflow）

在 JupyterLab 新增 notebooks/hello_mlflow.ipynb，貼上並執行：

import mlflow, random
mlflow.set_tracking_uri("http://mlflow:5000")  # 容器內用服務名
mlflow.set_experiment("anime-recsys")

with mlflow.start_run(run_name="hello-day1"):
    lr = 0.05
    acc = 0.8 + random.random() * 0.05
    mlflow.log_param("learning_rate", lr)
    mlflow.log_metric("accuracy", acc)
    # TODO: 建立 src/models 目錄，日後把 baseline 模型存成 artifact

回到 MLflow UI 就能看到你的第一筆實驗紀錄 🎉

重點總結

• 我們選定 動畫推薦 當案例，確立全流程目標。
• 用 docker-compose 一口氣啟動 Postgres＋MLflow＋Jupyter，且共用 mlops-net 網路，彼此可用服務名互通。
• 成功把第一筆實驗寫進 MLflow，之後就能版本化與比較。

延伸思考（預告 Day 2）

• Day 2 會深入 MLflow Tracking/Registry 的觀念與 UI 操作，並開始放入真正的推薦模型。
• 也會把資料夾與專案結構再收斂，為 FastAPI / Streamlit / AB Test 做鋪路。