feat: Image-Aware Model Routing

.github/workflows/docker-image-dev.yml

@@ -0,0 +1,152 @@
+name: Publish Docker image (dev)
+
+# Builds the full image (Dockerfile): frontend (web/default + classic) is
+# built with bun and embedded into the Go binary, so a single port (:3000)
+# serves both the API and the frontend. Pushed to the GitHub Container
+# Registry (ghcr.io) under this repo's owner namespace. Authenticates with
+# the built-in GITHUB_TOKEN, so no Docker Hub secrets are required.
+#
+# Each architecture is built natively in parallel (no QEMU emulation), then
+# merged into a single multi-arch manifest — much faster than a single
+# emulated multi-arch build.
+#
+# After the first publish, set the package to "public" at
+#   https://github.com/users/<owner>/packages/container/new-api/settings
+# so it can be pulled anonymously.
+
+on:
+  push:
+    branches:
+      - feat/image-aware-model-routing
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+  workflow_dispatch:
+    inputs:
+      name:
+        description: "reason"
+        required: false
+
+jobs:
+  build_single_arch:
+    name: Build & push (${{ matrix.arch }}) [native]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-latest
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Check out (shallow)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Resolve GHCR image name
+        id: ghcr
+        run: |
+          OWNER_LC=$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')
+          echo "image=ghcr.io/${OWNER_LC}/new-api" >> $GITHUB_OUTPUT
+
+      - name: Determine dev version
+        id: version
+        run: |
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          echo "versioned=dev-${SHORT_SHA}" >> $GITHUB_OUTPUT
+          echo "Publishing dev image for ${{ matrix.arch }}: dev, dev-${SHORT_SHA}"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build & push single-arch
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: ${{ matrix.platform }}
+          push: true
+          tags: |
+            ${{ steps.ghcr.outputs.image }}:dev-${{ matrix.arch }}
+            ${{ steps.ghcr.outputs.image }}:${{ steps.version.outputs.versioned }}-${{ matrix.arch }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Output digest
+        run: |
+          echo "### Dev image (${{ matrix.arch }})" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "${{ steps.ghcr.outputs.image }}:dev-${{ matrix.arch }}" >> $GITHUB_STEP_SUMMARY
+          echo "${{ steps.build.outputs.digest }}" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+  create_manifests:
+    name: Create multi-arch manifest
+    needs: [build_single_arch]
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Check out (shallow)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Resolve GHCR image name
+        id: ghcr
+        run: |
+          OWNER_LC=$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')
+          echo "image=ghcr.io/${OWNER_LC}/new-api" >> $GITHUB_OUTPUT
+
+      - name: Determine dev version
+        id: version
+        run: |
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          echo "versioned=dev-${SHORT_SHA}" >> $GITHUB_OUTPUT
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Create & push manifest (dev)
+        run: |
+          docker buildx imagetools create \
+            -t ${{ steps.ghcr.outputs.image }}:dev \
+            ${{ steps.ghcr.outputs.image }}:dev-amd64 \
+            ${{ steps.ghcr.outputs.image }}:dev-arm64
+
+      - name: Create & push manifest (versioned)
+        run: |
+          docker buildx imagetools create \
+            -t ${{ steps.ghcr.outputs.image }}:${{ steps.version.outputs.versioned }} \
+            ${{ steps.ghcr.outputs.image }}:${{ steps.version.outputs.versioned }}-amd64 \
+            ${{ steps.ghcr.outputs.image }}:${{ steps.version.outputs.versioned }}-arm64
+
+      - name: Output manifest digest
+        run: |
+          echo "### Multi-arch Manifest (dev)" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          docker buildx imagetools inspect ${{ steps.ghcr.outputs.image }}:dev >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

constant/context_key.go

@@ -19,6 +19,7 @@ const (
 	ContextKeyTokenModelLimitEnabled ContextKey = "token_model_limit_enabled"
 	ContextKeyTokenModelLimit        ContextKey = "token_model_limit"
 	ContextKeyTokenCrossGroupRetry   ContextKey = "token_cross_group_retry"
+	ContextKeyTokenModelRouteNotify  ContextKey = "token_model_route_notify"
 
 	/* channel related keys */
 	ContextKeyChannelId                ContextKey = "channel_id"
@@ -42,6 +43,10 @@ const (
 	ContextKeyAutoGroupIndex      ContextKey = "auto_group_index"
 	ContextKeyAutoGroupRetryIndex ContextKey = "auto_group_retry_index"
 
+	/* image-aware routing keys */
+	ContextKeyImageAwareEntryModel ContextKey = "image_aware_entry_model"
+	ContextKeyImageAwareHasImage   ContextKey = "image_aware_has_image"
+
 	/* user related keys */
 	ContextKeyUserId      ContextKey = "id"
 	ContextKeyUserSetting ContextKey = "user_setting"

controller/token.go

@@ -221,6 +221,7 @@ func AddToken(c *gin.Context) {
 		AllowIps:           token.AllowIps,
 		Group:              token.Group,
 		CrossGroupRetry:    token.CrossGroupRetry,
+		ModelRouteNotify:   token.ModelRouteNotify,
 	}
 	err = cleanToken.Insert()
 	if err != nil {
@@ -299,6 +300,7 @@ func UpdateToken(c *gin.Context) {
 		cleanToken.AllowIps = token.AllowIps
 		cleanToken.Group = token.Group
 		cleanToken.CrossGroupRetry = token.CrossGroupRetry
+		cleanToken.ModelRouteNotify = token.ModelRouteNotify
 	}
 	err = cleanToken.Update()
 	if err != nil {

docker-compose.deploy.yml

@@ -0,0 +1,71 @@
+# Deployment compose - pulls the dev image published to the GitHub Container
+# Registry by CI (.github/workflows/docker-image-dev.yml). The image is built
+# from Dockerfile.dev (backend-only, frontend served by the image placeholder).
+#
+# If the GHCR package is private, log in first:
+#   echo $GITHUB_TOKEN | docker login ghcr.io -u <owner> --password-stdin
+#
+# Usage:
+#   1. docker compose -f docker-compose.deploy.yml up -d
+#   2. Open http://localhost:3000
+#
+# Stop:
+#   docker compose -f docker-compose.deploy.yml down
+#
+# Reset data:
+#   docker compose -f docker-compose.deploy.yml down -v
+
+services:
+  new-api:
+    image: ghcr.io/gentle-lijie/new-api:dev
+    container_name: new-api-deploy
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    volumes:
+      - deploy_data:/data
+    environment:
+      - SQL_DSN=postgresql://root:123456@postgres:5432/new-api
+      - REDIS_CONN_STRING=redis://redis
+      - TZ=Asia/Shanghai
+      - BATCH_UPDATE_ENABLED=true
+    depends_on:
+      redis:
+        condition: service_started
+      postgres:
+        condition: service_healthy
+    networks:
+      - deploy-network
+
+  redis:
+    image: redis:7-alpine
+    container_name: new-api-deploy-redis
+    restart: unless-stopped
+    networks:
+      - deploy-network
+
+  postgres:
+    image: postgres:15-alpine
+    container_name: new-api-deploy-pg
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: root
+      POSTGRES_PASSWORD: 123456
+      POSTGRES_DB: new-api
+    volumes:
+      - deploy_pg_data:/var/lib/postgresql/data
+    networks:
+      - deploy-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U root -d new-api"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  deploy_data:
+  deploy_pg_data:
+
+networks:
+  deploy-network:
+    driver: bridge

docs/PR-description.md

@@ -0,0 +1,46 @@
+> [!IMPORTANT]
+> 本 PR 由 AI 辅助生成（git user `GentleLijie` 非历史核心开发者），已人工整理描述如下。
+
+## 📝 变更描述 / Description
+
+新增「图片感知模型路由」：配置一个**虚拟入口模型名**（如 `auto-coder`），网关在 distributor 选渠道之前，解析请求体检测**最后一条 `role=user` 消息**是否含图片（同时支持 OpenAI `image_url` 与 Claude `image` 两种 content part），据此把模型名改写为配置好的**视觉模型**或**编程模型**。改写发生在渠道选择之前，因此真实模型名会参与渠道选择、亲和性、计费与重试。
+
+由于网关每个请求无状态，“图片轮走视觉模型、后续纯文本轮回到编程模型”由客户端每轮携带的完整对话历史天然完成，网关无需存任何状态——仅看当前轮最后一条 user 消息，避免历史残留图片误触发。
+
+可观测性：
+- 响应头注入 `X-Routed-Model` / `X-Route-Entry-Model` / `X-Route-Reason`
+- Token 级 `ModelRouteNotify` 开关（默认对新 token 开启）控制是否在**响应体内**注入提示文本（如 `> [Route: auto-coder → glm-4.6v (image detected)]`），覆盖 OpenAI/Claude 客户端格式 × 流式/非流式
+- 日志 `Log.Other` 写入 `image_aware_entry_model`，用量日志 Model 列显示相机图标 + 入口模型 Popover
+
+管理后台提供向导式 Drawer 配置路由规则（入口模型 + 视觉/编程模型下拉选择）。
+
+## 🚀 变更类型 / Type of change
+- [x] ✨ 新功能 (New feature)
+
+## 🔗 关联任务 / Related Issue
+- 无对应 Issue
+
+## ✅ 提交前检查项 / Checklist
+- [x] **非重复提交:** 已确认无重复 PR
+- [x] **变更理解:** 见上方描述
+- [x] **范围聚焦:** 排除了无关的 `__root.tsx`（devtools 注释）与 `pnpm-lock.yaml`（npm 误生成）
+- [x] **本地验证:** 后端 `go build ./...` 通过；`go test ./middleware/`（图片检测表驱动单测 12 例）通过；前端 `tsc -b` 涉及文件无类型错误
+- [x] **安全合规:** 无敏感凭据；JSON 统一走 `common.*`；配置仅写 options 表字符串，三库兼容
+
+> 注：checklist 中「人工确认」项因本 PR 为 AI 辅助生成，未勾选，已在此如实标注。
+
+## 📸 运行证明 / Proof of Work
+
+带图请求被正确路由到视觉模型，纯文本请求回到编程模型（`record consume log` 的 `model_name` 字段）：
+```text
+model_name=glm-4.6v  prompt_tokens=41355  image_aware_entry_model=auto-coder   // 含图 → 视觉模型
+model_name=glm-5     prompt_tokens=79     image_aware_entry_model=auto-coder   // 纯文本 → 编程模型
+model_name=glm-5     prompt_tokens=41188  image_aware_entry_model=auto-coder   // 后续纯文本轮，仍回编程模型
+```
+
+路由决策日志（distributor，每请求一次，不刷屏）：
+```text
+image_aware_routing: entry=auto-coder has_image=true -> routed=glm-4.6v notify=true
+```
+
+Token 开启 `ModelRouteNotify` 后，响应流首个内容 delta 前置提示文本，客户端可见 `> [Route: auto-coder → glm-4.6v (image detected)]`。