![image.png](/static/img/1a5d3f2a89bf06ab94bd0d3281444a04.image.webp)



```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import numpy as np
import matplotlib.pyplot as plt


def IWP_Model_Controlled(u, X, h, J1, J2, l1, l2, c1, c2, m1, m2, Kb, Kt, Ra, g):
    theta, theta_dot, phi, phi_dot = X
    A = np.array([
        [m1 * l1 ** 2 + m2 * l2 ** 2 + J1 + J2, J2],
        [J2, J2]
    ])
    B = np.array([
        [c1, 0],
        [0, (Kt * Kb / Ra) + c2]
    ])
    C = np.array([
        -(m1 * l1 + m2 * l2) * g * np.sin(theta),
        Kt * u / Ra
    ])
    acceleration = np.linalg.inv(A).dot(-B.dot(np.array([theta_dot, phi_dot])) + C)
    dXdt = np.array([theta_dot, acceleration[0], phi_dot, acceleration[1]])
    next_X = X + h * dXdt
    return next_X


class ADRC:
    def __init__(self, dt, r, h, beta1, beta2, beta3, k1, k2, b0):
        self.dt = dt
        self.r = r
        self.h = h
        self.beta1 = beta1
        self.beta2 = beta2
        self.beta3 = beta3
        self.k1 = k1
        self.k2 = k2
        self.b0 = b0
        self.v1 = 0.0
        self.v2 = 0.0
        self.z1 = 0.0
        self.z2 = 0.0
        self.z3 = 0.0
        self.u_prev = 0.0

    def fhan(self, x1, x2, r, h):
        d = r * h
        d0 = h * d
        y = x1 + h * x2
        a0 = np.sqrt(d ** 2 + 8 * r * abs(y))
        if abs(y) > d0:
            a = x2 + (a0 - d) / 2 * np.sign(y)
        else:
            a = x2 + y / h
        if abs(a) > d:
            return -r * np.sign(a)
        else:
            return -r * a / d

    def TD(self, target):
        e = self.v1 - target
        fh = self.fhan(e, self.v2, self.r, self.h)
        self.v1 += self.dt * self.v2
        self.v2 += self.dt * fh
        return self.v1, self.v2

    def ESO(self, y, u):
        e = self.z1 - y
        self.z1 += self.dt * (self.z2 - self.beta1 * e)
        self.z2 += self.dt * (self.z3 + self.b0 * u - self.beta2 * e)
        self.z3 += self.dt * (-self.beta3 * e)
        return self.z1, self.z2, self.z3

    def NLSEF(self, v1, v2, z1, z2):
        e1 = v1 - z1
        e2 = v2 - z2
        return self.k1 * e1 + self.k2 * e2

    def control(self, y, target):
        v1, v2 = self.TD(target)
        z1, z2, z3 = self.ESO(y, self.u_prev)
        u0 = self.NLSEF(v1, v2, z1, z2)
        u = (u0 - z3) / self.b0
        self.u_prev = u
        return u


def iwp_adrc_discrete():
    J1 = 0.01186
    J2 = 0.0005711
    l1 = 0.1053
    l2 = 0.14
    c1 = 0.04
    c2 = 0.0001
    m1 = 0.826
    m2 = 0.583
    Kb = 0.0987
    Kt = 0.0987
    Ra = 1.5562
    g = 9.81

    dt = 0.001
    t_total = 3
    t_steps = int(t_total / dt)

    a = m1 * l1 ** 2 + m2 * l2 ** 2 + J1 + J2
    b0 = - (Kt / (Ra * (a - J2)))
    print(b0)

    r = 30
    beta1 = 300
    beta2 = 30000
    beta3 = 1e6
    k1 = 150
    k2 = 50

    adrc = ADRC(dt, r, dt, beta1, beta2, beta3, k1, k2, b0)

    theta0 = np.deg2rad(-10)
    theta_dot0 = 0.0
    phi0 = 0.0
    phi_dot0 = 0.0
    X = np.array([theta0, theta_dot0, phi0, phi_dot0])

    theta_ref = 0.0

    theta_history = np.zeros(t_steps)
    theta_dot_history = np.zeros(t_steps)
    phi_dot_history = np.zeros(t_steps)
    time_history = np.zeros(t_steps)
    control_history = np.zeros(t_steps)

    for i in range(t_steps):
        current_time = i * dt
        current_theta = X[0]
        Vm = adrc.control(current_theta, theta_ref)
        Vm = np.clip(Vm, -50, 50)
        X = IWP_Model_Controlled(Vm, X, dt, J1, J2, l1, l2, c1, c2, m1, m2, Kb, Kt, Ra, g)

        theta_history[i] = np.rad2deg(X[0])
        theta_dot_history[i] = X[1]
        phi_dot_history[i] = X[3]
        control_history[i] = Vm
        time_history[i] = current_time

    plt.figure(figsize=(12, 5))

    plt.subplot(1, 2, 1)
    plt.plot(time_history, theta_history, label='Pendulum Angle')
    plt.plot(time_history, np.zeros_like(time_history), 'r--', label='Target (0°)')
    plt.xlabel('Time (s)')
    plt.ylabel('Angle (°)')
    plt.title('Pendulum Angle Response (θ)')
    plt.grid(True)
    plt.legend()

    plt.subplot(1, 2, 2)
    plt.plot(time_history, phi_dot_history, label='Wheel Angular Velocity')
    plt.xlabel('Time (s)')
    plt.ylabel('Angular Velocity (rad/s)')
    plt.title('Wheel Angular Velocity Response (φ̇)')
    plt.grid(True)
    plt.legend()

    plt.tight_layout()
    plt.show()


if __name__ == '__main__':
    iwp_adrc_discrete()
```

ADRC算法平衡惯性轮倒立摆的代码

![image.png](/static/img/2f1466bf2f270287c78604a972d21c30.image.webp)



```python
import numpy as np
import matplotlib.pyplot as plt

# 倒立摆参数
M = 1.0  # 小车质量 (kg)
m = 0.1  # 摆杆质量 (kg)
l = 0.5  # 摆杆长度 (m)
g = 9.81  # 重力加速度 (m/s²)


# 倒立摆动力学模型
def pendulum_model(state, F):
    x, x_dot, theta, theta_dot = state
    sin_theta = np.sin(theta)
    cos_theta = np.cos(theta)

    # 计算theta''
    numerator = (M + m) * g * sin_theta - F * cos_theta - m * l * theta_dot ** 2 * sin_theta * cos_theta
    denominator = l * (M + m - m * cos_theta ** 2)
    denominator = np.sign(denominator) * max(1e-6, abs(denominator))  # 避免除以零
    theta_ddot = numerator / denominator

    # 计算x''
    if abs(cos_theta) < 1e-6:
        cos_theta = np.sign(cos_theta) * 1e-6
    x_ddot = (g * sin_theta - l * theta_ddot) / cos_theta

    return np.array([x_dot, x_ddot, theta_dot, theta_ddot])


class ADRC:
    def __init__(self, dt, r, h, beta1, beta2, beta3, k1, k2, b0):
        self.dt = dt
        self.r = r
        self.h = h
        self.beta1 = beta1
        self.beta2 = beta2
        self.beta3 = beta3
        self.k1 = k1
        self.k2 = k2
        self.b0 = b0

        # 状态初始化
        self.v1 = 0.0
        self.v2 = 0.0
        self.z1 = 0.0
        self.z2 = 0.0
        self.z3 = 0.0
        self.u_prev = 0.0

    def fhan(self, x1, x2, r, h):
        d = r * h
        d0 = h * d
        y = x1 + h * x2
        a0 = np.sqrt(d ** 2 + 8 * r * np.abs(y))

        if np.abs(y) > d0:
            a = x2 + (a0 - d) / 2 * np.sign(y)
        else:
            a = x2 + y / h

        if np.abs(a) > d:
            return -r * np.sign(a)
        else:
            return -r * a / d

    def TD(self, target):
        e = self.v1 - target
        fh = self.fhan(e, self.v2, self.r, self.h)
        self.v1 += self.dt * self.v2
        self.v2 += self.dt * fh
        return self.v1, self.v2

    def ESO(self, y, u):
        e = self.z1 - y
        self.z1 += self.dt * (self.z2 - self.beta1 * e)
        self.z2 += self.dt * (self.z3 + self.b0 * u - self.beta2 * e)
        self.z3 += self.dt * (-self.beta3 * e)
        return self.z1, self.z2, self.z3

    def NLSEF(self, v1, v2, z1, z2):
        e1 = v1 - z1
        e2 = v2 - z2
        return self.k1 * e1 + self.k2 * e2

    def control(self, y, target):
        v1, v2 = self.TD(target)
        z1, z2, z3 = self.ESO(y, self.u_prev)
        u0 = self.NLSEF(v1, v2, z1, z2)
        u = (u0 - z3) / self.b0
        self.u_prev = u
        return u


# 仿真参数
dt = 0.001
sim_time = 5.0
t = np.arange(0, sim_time, dt)
n = len(t)

# 初始状态 (x, x_dot, theta, theta_dot)
state = np.array([0.0, 0.0, np.pi / 6, 0.0])  # 初始角度30度

# ADRC参数
b0 = -1 / (l * M)  # 控制增益
adrc = ADRC(
    dt=dt,
    r=30,  # TD速度因子
    h=dt,  # TD滤波因子
    beta1=300,  # ESO参数 (3w)
    beta2=30000,  # (3w^2)
    beta3=1e6,  # (w^3)
    k1=150,  # NLSEF增益
    k2=50,
    b0=b0
)

# 初始化记录数组
states = np.zeros((n, 4))
F_history = np.zeros(n)
theta_history = np.zeros(n)

# 主循环
for i in range(n):
    # 获取当前角度作为系统输出
    current_theta = state[2]

    # ADRC控制
    F = adrc.control(current_theta, 0.0)
    F = np.clip(F, -50, 50)  # 限制控制力

    # 记录状态
    states[i] = state
    F_history[i] = F
    theta_history[i] = current_theta

    # 更新状态
    state_deriv = pendulum_model(state, F)
    state += state_deriv * dt

    # 角度归一化到[-pi, pi]
    if state[2] > np.pi:
        state[2] -= 2 * np.pi
    elif state[2] < -np.pi:
        state[2] += 2 * np.pi

# 绘图
plt.figure(figsize=(12, 8))
plt.subplot(2, 1, 1)
plt.plot(t, np.degrees(theta_history), label='Theta')  # 将弧度转换为度数
plt.plot([0, sim_time], [0, 0], 'r--', label='Target')
plt.ylabel('Angle (degrees)')  # 修改ylabel为度数
plt.legend()
plt.grid(True)

plt.subplot(2, 1, 2)
plt.plot(t, F_history, label='Control Force')
plt.ylabel('Force (N)')
plt.xlabel('Time (s)')
plt.legend()
plt.grid(True)

plt.tight_layout()
plt.show()
```

ADRC算法平衡倒立摆的代码

## API调用

登录这里：
https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint?config=%7B%7D

注册后，创建DeepSeek R1 API接入点：

![image.png](/static/img/f7bd0508dac987671565f7b081c4efe6.image.webp)



接着Python就可以直接调用了：

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key = "填写自己的key",
    base_url = "https://ark.cn-beijing.volces.com/api/v3",
)

# Non-streaming:
print("----- standard request -----")
completion = client.chat.completions.create(
    model = "ep-20250211175825-填写自己的模型名字",  # your model endpoint ID
    messages = [
        {"role": "system", "content": "你是豆包，是由字节跳动开发的 AI 人工智能助手"},
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
)
print(completion.choices[0].message.content)

```

## OpenWebUI使用

安装：

```
docker run -d -p 8888:8080 \
  -v /root/ollama:/root/.ollama \
  -v /root/openwebui-test:/app/backend/data \
  --restart always -e HF_HUB_OFFLINE=1 \
  ghcr.io/open-webui/open-webui:ollama
```

增加这个函数到OpenWebUI：

```bash
"""
title: DeepSeek R1
author: zgccrui
description: 在OpwenWebUI中显示DeepSeek R1模型的思维链 - 仅支持0.5.6及以上版本
version: 1.2.6
licence: MIT
"""

import json
import httpx
import re
from typing import AsyncGenerator, Callable, Awaitable
from pydantic import BaseModel, Field
import asyncio


class Pipe:
    class Valves(BaseModel):
        DEEPSEEK_API_BASE_URL: str = Field(
            default="自己的baseurl",
            description="Base Url",
        )
        DEEPSEEK_API_KEY: str = Field(
            default="", description="用于身份验证的DeepSeek API密钥，可从控制台获取"
        )
        DEEPSEEK_API_MODEL: str = Field(
            default="deepseek-reasoner",
            description="API请求的模型名称，默认为 deepseek-reasoner ",
        )

    def __init__(self):
        self.valves = self.Valves()
        self.data_prefix = "data: "
        self.thinking = -1  # -1:未开始 0:思考中 1:已回答
        self.emitter = None

    def pipes(self):
        return [
            {
                "id": self.valves.DEEPSEEK_API_MODEL,
                "name": self.valves.DEEPSEEK_API_MODEL,
            }
        ]

    async def pipe(
        self, body: dict, __event_emitter__: Callable[[dict], Awaitable[None]] = None
    ) -> AsyncGenerator[str, None]:
        """主处理管道（已移除缓冲）"""
        self.thinking = -1
        self.emitter = __event_emitter__

        # 验证配置
        if not self.valves.DEEPSEEK_API_KEY:
            yield json.dumps({"error": "未配置API密钥"}, ensure_ascii=False)
            return

        # 准备请求参数
        headers = {
            "Authorization": f"Bearer {self.valves.DEEPSEEK_API_KEY}",
            "Content-Type": "application/json",
        }

        try:
            # 模型ID提取
            model_id = body["model"].split(".", 1)[-1]
            payload = {**body, "model": model_id}

            # 处理消息以防止连续的相同角色
            messages = payload["messages"]
            i = 0
            while i < len(messages) - 1:
                if messages[i]["role"] == messages[i + 1]["role"]:
                    # 插入具有替代角色的占位符消息
                    alternate_role = (
                        "assistant" if messages[i]["role"] == "user" else "user"
                    )
                    messages.insert(
                        i + 1,
                        {"role": alternate_role, "content": "[Unfinished thinking]"},
                    )
                i += 1

            # yield json.dumps(payload, ensure_ascii=False)

            # 发起API请求
            async with httpx.AsyncClient(http2=True) as client:
                async with client.stream(
                    "POST",
                    f"{self.valves.DEEPSEEK_API_BASE_URL}/chat/completions",
                    json=payload,
                    headers=headers,
                    timeout=300,
                ) as response:
                    # 错误处理
                    if response.status_code != 200:
                        error = await response.aread()
                        yield self._format_error(response.status_code, error)
                        return

                    # 流式处理响应
                    async for line in response.aiter_lines():
                        if not line.startswith(self.data_prefix):
                            continue

                        # 截取 JSON 字符串
                        json_str = line[len(self.data_prefix) :]

                        try:
                            data = json.loads(json_str)
                        except json.JSONDecodeError as e:
                            # 格式化错误信息，这里传入错误类型和详细原因（包括出错内容和异常信息）
                            error_detail = f"解析失败 - 内容：{json_str}，原因：{e}"
                            yield self._format_error("JSONDecodeError", error_detail)
                            return

                        choice = data.get("choices", [{}])[0]

                        # 结束条件判断
                        if choice.get("finish_reason"):
                            return

                        # 状态机处理
                        state_output = await self._update_thinking_state(
                            choice.get("delta", {})
                        )
                        if state_output:
                            yield state_output  # 直接发送状态标记
                            if state_output == "<think>":
                                yield "\n"

                        # 内容处理并立即发送
                        content = self._process_content(choice["delta"])
                        if content:
                            if content.startswith("<think>"):
                                match = re.match(r"^<think>", content)
                                if match:
                                    content = re.sub(r"^<think>", "", content)
                                    yield "<think>"
                                    await asyncio.sleep(0.1)
                                    yield "\n"

                            elif content.startswith("</think>"):
                                match = re.match(r"^</think>", content)
                                if match:
                                    content = re.sub(r"^</think>", "", content)
                                    yield "</think>"
                                    await asyncio.sleep(0.1)
                                    yield "\n"
                            yield content

        except Exception as e:
            yield self._format_exception(e)

    async def _update_thinking_state(self, delta: dict) -> str:
        """更新思考状态机（简化版）"""
        state_output = ""

        # 状态转换：未开始 -> 思考中
        if self.thinking == -1 and delta.get("reasoning_content"):
            self.thinking = 0
            state_output = "<think>"

        # 状态转换：思考中 -> 已回答
        elif (
            self.thinking == 0
            and not delta.get("reasoning_content")
            and delta.get("content")
        ):
            self.thinking = 1
            state_output = "\n</think>\n\n"

        return state_output

    def _process_content(self, delta: dict) -> str:
        """直接返回处理后的内容"""
        return delta.get("reasoning_content", "") or delta.get("content", "")

    def _format_error(self, status_code: int, error: bytes) -> str:
        """错误格式化保持不变"""
        try:
            err_msg = json.loads(error).get("message", error.decode(errors="ignore"))[
                :200
            ]
        except:
            err_msg = error.decode(errors="ignore")[:200]
        return json.dumps(
            {"error": f"HTTP {status_code}: {err_msg}"}, ensure_ascii=False
        )

    def _format_exception(self, e: Exception) -> str:
        """异常格式化保持不变"""
        err_type = type(e).__name__
        return json.dumps({"error": f"{err_type}: {str(e)}"}, ensure_ascii=False)

```

保存函数，配置函数参数：


![image.png](/static/img/da12b1b2235d9d6cfa4fe7ce8f5462a3.image.webp)

## 使用

可以自己修改一个模型名称便于认识，然后这个函数就可以显示出思考过程了。

![image.png](/static/img/b3fe3411c4f6fa3aaf6de917ef428f81.image.webp)

OpenWebUI使用DeepSeek R1满血版，DeepSeek R1 API调用

安装 Docker Compose 可以通过几种方式进行，最常见的是通过下载官方提供的二进制文件或者使用包管理器安装。以下是两种主要的方法：



### 方法一：通过下载二进制文件安装 Docker Compose

1. **下载最新版本的 Docker Compose**：
   
   首先，确定最新版本的 Docker Compose。你可以在 [GitHub Releases](https://github.com/docker/compose/releases) 页面找到最新版本。目前最新的稳定版本是 1.29.2（截至2021年）。

   使用以下命令下载：

   ```bash
   sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
   ```

2. **设置执行权限**：

   下载完成后，你需要为二进制文件设置执行权限：

   ```bash
   sudo chmod +x /usr/local/bin/docker-compose
   ```

3. **创建符号链接（可选）**：

   为了避免打字错误或者简化路径，可以创建一个符号链接到 `/usr/bin`：

   ```bash
   sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
   ```

4. **验证安装**：

   最后，使用以下命令验证安装是否成功：

   ```bash
   docker-compose --version
   ```

### 方法二：通过包管理器安装 Docker Compose

如果你更喜欢通过包管理器来管理软件，可以使用 Python 的包管理工具 `pip` 来安装 Docker Compose。

1. **安装 pip**：

   首先，确保你已经安装了 `pip`。如果没有，可以使用以下命令来安装：

   ```bash
   sudo apt update
   sudo apt install -y python3-pip
   ```

2. **使用 pip 安装 Docker Compose**：

   使用 `pip` 安装 Docker Compose：

   ```bash
   sudo pip3 install docker-compose
   ```

3. **验证安装**：

   使用以下命令验证安装是否成功：

   ```bash
   docker-compose --version
   ```

### 方法三：通过官方 APT 源安装 Docker Compose Plugin

Docker 现在提供了 Docker Compose 的插件版本，可以直接与 Docker CLI 集成。

1. **更新包索引并安装 Docker Compose 插件**：

   ```bash
   sudo apt update
   sudo apt install -y docker-compose-plugin
   ```

2. **验证安装**：

   你可以使用以下命令来确保安装成功：

   ```bash
   docker compose version
   ```

无论你选择哪种方法，都应该能够成功安装 Docker Compose 并开始使用它来定义和管理多容器 Docker 应用。

Ubuntu22 安装Docker Compose

在 Ubuntu 22.04 上安装 Docker 是一个相对简单的过程。以下是步骤：

### 1. 更新系统包

首先，确保系统包信息是最新的：

```bash
sudo apt update
sudo apt upgrade -y
```



### 2. 安装依赖包

在安装 Docker 之前，需要一些依赖包：

```bash
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
```

### 3. 添加 Docker 的官方 GPG 密钥

为了确保下载软件包的安全性，我们需要添加 Docker 的官方 GPG 密钥：

```bash
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
```

### 4. 添加 Docker 的 APT 源

将 Docker 的 APT 源添加到你的系统中：

```bash
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```

### 5. 更新包索引

添加 Docker 的软件源之后，需要更新 APT 包索引：

```bash
sudo apt update
```

### 6. 安装 Docker 引擎

现在可以安装 Docker 引擎了：

```bash
sudo apt install -y docker-ce docker-ce-cli containerd.io
```

### 7. 启动并启用 Docker

安装完成后，启动 Docker 并设置开机自启：

```bash
sudo systemctl start docker
sudo systemctl enable docker
```

### 8. 验证安装

运行以下命令查看 Docker 的版本，并确保 Docker 报告了其版本信息：

```bash
docker --version
```

还可以运行一个简单的测试容器，确保 Docker 工作正常：

```bash
sudo docker run hello-world
```

### 9. （可选）将当前用户加入 `docker` 组

为了不在每次运行 Docker 命令时都使用 `sudo`，可以将当前用户加入 `docker` 组：

```bash
sudo usermod -aG docker $USER
```

然后，重新登录或重新启动系统以使更改生效。

现在，你已经在 Ubuntu 22.04 上成功安装了 Docker！

Ubuntu22 安装Docker

本文作为这篇文章的总结：

https://mp.weixin.qq.com/s/-rXYgsu_1IEpjGvSQArPJQ



### 深入解析FlashAttention的核心原理与优化策略

#### **FlashAttention的核心价值**
- **问题背景**：Transformer的Attention模块存在计算效率瓶颈，传统优化方法（如稀疏近似）虽减少计算量（FLOPs），但未解决关键I/O瓶颈。
- **三大优势**：
  1. **I/O感知的高效计算**：通过优化内存访问模式（减少HBM访问次数）而非仅减少FLOPs提速。
  2. **内存高效**：分块计算（Tiling）避免存储中间矩阵（如QK^T），显著降低内存占用。
  3. **精确计算**：结果与原始Attention完全一致，避免近似算法的误差。

---

#### **数学原理：从Softmax到FlashAttention**

1. **安全Softmax**：通过减去最大值防止数值溢出，但需三次遍历数据。

    Softmax的原始公式：
    $$
    s_i=\frac{e^{x_i}}{\sum_{j=1}^N e^{x_j}}
    $$
    安全Softmax：
    $$
    S_i=\frac{\frac{e^{x_i}}{e^{m_N}}}{\sum_{j=1}^K\left(\frac{e^{x_j}}{e^{m_N}}\right)}=\frac{e^{x_i-m_N}}{\sum_{j=1}^K\left(e^{x_j-m_N}\right)}
    $$
2. **Online Softmax**（Nvidia提出）：
   - **递归思想**：逐元素计算局部最大值和归一化因子，将三次遍历降为两次。
3. **FlashAttention的突破**：
   - **融合计算**：将Softmax与Value矩阵乘法结合，通过分块迭代公式实现单次遍历。
   - **避免中间存储**：直接计算Attention结果，无需保存QK^T和Softmax矩阵。

---

#### **硬件视角：为什么需要FlashAttention？**
- **GPU/NPU内存瓶颈**：
  - **HBM**：容量大（40GB）但带宽低（1.5TB/s）。
  - **SRAM**：带宽高（19TB/s）但容量小（20MB）。
- **计算膨胀系数β**：矩阵乘法（β=O(d)）易受计算带宽限制，Softmax（β≈3）受内存带宽限制。
- **分块策略**：将大矩阵拆分为小块，在SRAM中完成计算，减少HBM交互次数。

---

#### **算法演进：FA-1到FA-3的核心优化**
1. **FA-1**（基础版本）：
   - **外循环分块**：按Q的行分块，内循环加载K/V块，逐块计算Softmax并累加结果。
   - **避免中间矩阵**：融合Softmax与矩阵乘，仅保存最终Attention结果。
2. **FA-2**：
   - **循环结构调整**：将Q作为外循环，K/V为内循环，减少数据重复加载。
   - **计算式优化**：调整Softmax迭代公式，减少除法操作（式4-12），最后统一归一化。
3. **FA-3**（硬件级优化）：
   - **异步计算**：利用H100的Tensor Core异步执行GEMM与Softmax。
   - **低精度加速**：支持FP8计算，提升吞吐量。

---

#### **面试常见问题**
1. **FlashAttention为何比传统Attention快？**
   - 关键在减少HBM访问次数，通过分块计算和融合Softmax与矩阵乘，避免存储中间矩阵。

2. **如何保证计算精确性？**
   - 采用安全Softmax的数学变形，通过局部归一化因子递归计算，结果与原始算法一致。

3. **FA-2相比FA-1改进点？**
   - 外循环调整为Q分块，减少数据加载；优化Softmax迭代公式，减少非矩阵运算。

4. **分块大小如何选择？**
   - 受SRAM容量限制，需确保每个块的计算在SRAM内完成，典型配置为块大小≤128x128。


![image.png](/static/img/a63f18baaa685381e6a9e5e1f5516edf.image.webp)

---

#### **总结**
FlashAttention通过**分块计算**与**迭代式Softmax**的巧妙结合，在保证计算精度的同时，大幅降低内存访问开销，成为大模型训练的关键优化。其设计思想揭示了AI计算中“内存效率优先于计算量”的核心原则，为后续硬件感知算法提供了范本。

FlashAttention 透彻理解

https://www.modelscope.cn/models/iic/cv_ddcolor_image-colorization/summary#ddcolor-%E5%9B%BE%E5%83%8F%E4%B8%8A%E8%89%B2%E6%A8%A1%E5%9E%8B



本博客的代码：https://github.com/xxddccaa/DDColor-webui


## 下载模型


```
pip install modelscope


modelscope download --model 'iic/cv_ddcolor_image-colorization' --local_dir './DDColormodel'

```

## 推理
pytroch环境：

```
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia -y

pip install addict modelscope datasets sympy==1.13.1 simplejson sortedcontainers timm
```

推理：
```python
import cv2
from modelscope.outputs import OutputKeys
from modelscope.pipelines import pipeline
from modelscope.utils.constant import Tasks

img_colorization = pipeline(Tasks.image_colorization, 
                       model='./DDColormodel')
img_path = 'https://modelscope.oss-cn-beijing.aliyuncs.com/test/images/audrey_hepburn.jpg'
result = img_colorization(img_path)
cv2.imwrite('result.png', result[OutputKeys.OUTPUT_IMG])
```

原图：

![audrey_hepburn.jpg](/static/img/c6024d7a0f0ab002e4133224881120af.audrey_hepburn.webp)


![result.png](/static/img/fda6112455c6e6e6ccc94914c2f612d8.result.webp)

## docker环境

```
docker run --gpus all --shm-size=32g -it --net host -v ./:/ddcolor kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-pix2pix bash

pip install addict modelscope datasets sympy==1.13.1 simplejson sortedcontainers timm opencv-python

apt-get update
apt-get install -y libgl1-mesa-glx libjpeg-dev libpng-dev libtiff-dev libopencv-dev

docker commit 731cbf160933 kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor

docker push kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor
```

## webui部署

```
cd /ssd/xiedong/image_color

docker run --gpus device=2 \
--shm-size=32g \
-it \
--net host \
-v ./ddcolor_app.py:/ddcolor/ddcolor_app.py \
-v ./DDColormodel:/DDColormodel/ \
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor bash

pip install gradio

python /ddcolor/ddcolor_app.py --model_path /DDColormodel --port 7861
```

用这个镜像也ok：


```
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor-webui
```

![image.png](/static/img/737c2afbb63c0a73eb8d72ca768769ce.image.webp)


## 指标测试

```bash
docker run --gpus device=2 \
--shm-size=32g \
-it \
--net host \
-v /ssd/xiedong/image_color:/ssd/xiedong/image_color \
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor-webui bash


pip install evaluation_requirements.txt
```

转换测试图片：
```bash
python ddcolor_inference.py \
--model_path /ssd/xiedong/image_color/DDColormodel/ \
--src_dir /ssd/xiedong/image_color/pytorch-CycleGAN-and-pix2pix/results/tongyong_l2ab_4/testA_35/images \
--dst_dir /ssd/xiedong/image_color/ddcolor_test
```

得到指标：

```
python evaluate_colorization.py --results_dir /ssd/xiedong/image_color/ddcolor_test --output_dir /ssd/xiedong/image_color/ddcolor_test_metric  --use_fid
```

| Metric          | Mean      | Std Dev   | Min      | Max       | Performance Assessment      |
|----------------|-----------|-----------|----------|-----------|-----------------------------|
| SSIM           | 0.887     | 0.078     | 0.435    | 0.983     | ✅ ​**​Excellent​**​ (Ideal >0.85) |
| PSNR (dB)      | 21.65     | 3.63      | 8.91     | 31.73     | ⚠️ ​**​Good​**​ (Typical 20-30dB) |
| MSE            | 663.11    | 860.43    | 43.67    | 8349.47   | ⚠️ ​**​Moderate​**​ (Lower better)|
| MAE            | 16.25     | 8.20      | 2.55     | 72.02     | ⚠️ ​**​Acceptable​**​            |
| Color Error    | 11.39     | 7.55      | 1.46     | 54.99     | ⚠️ ​**​Needs Improvement​**​     |
| LPIPS          | 0.166     | 0.072     | 0.025    | 0.472     | ✅ ​**​Good​**​ (Closer to 0 best)|
| FID            | 36.51     | -         | -        | -         | ⚠️ ​**​Fair​**​ (Ideal <30)      |


镜像：

```
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor-webui-metric
```

## webui快速启动


webui 7861
```bash
cd /your/path/to/image_color

docker run --gpus device=2 \
--shm-size=32g \
-it \
--net host \
-v ./ddcolor_app.py:/ddcolor/ddcolor_app.py \
-v ./DDColormodel:/DDColormodel/ \
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor-webui-metric bash


python /ddcolor/ddcolor_app.py --model_path /DDColormodel --port 7861
```

webui 7862
```bash
cd /your/path/to/image_color

docker run --gpus device=2 \
--shm-size=32g \
-it \
--net host \
-v ./ddcolor_app.py:/ddcolor/ddcolor_app.py \
-v ./DDColormodel:/DDColormodel/ \
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-ddcolor-webui-metric bash


python /ddcolor/ddcolor_app.py --model_path /DDColormodel --port 7862
```

DDColor 效果实战教程

![image.png](/static/img/1b321dd10474f3d3e9bff1081cc767f5.image.webp)

随着深度学习的兴起，自动上色引起了很多关注，目标是在复杂的图像语义（如形状、纹理和上下文）中生成合适的颜色。一些早期方法尝试使用卷积神经网络（CNN）预测每个像素的颜色分布。不幸的是，这些基于CNN的方法由于缺乏对图像语义的全面理解，通常会产生不正确或不饱和的上色结果（图1中的CIC、InstColor和DeOldify）。为了更好地理解语义信息，一些方法借助生成对抗网络（GANs），利用它们丰富的表示作为上色的生成先验。然而，由于GAN先验的表示空间有限，它们无法处理具有复杂结构和语义的图像，导致不合适的上色结果或不愉快的伪影（图1中的Wu等和BigColor）。



随着自然语言处理（NLP）的巨大成功，Transformer已经扩展到许多计算机视觉任务。最近，一些工作将Transformer的非局部注意力机制引入图像上色。尽管取得了令人满意的结果，这些方法要么训练了几个独立的子网，导致累积误差（图1中的ColTran），要么在单尺度图像特征图上执行颜色注意操作，在处理复杂图像上下文时会导致明显的颜色晕染（图1中的CT2和ColorFormer）。此外，这些方法通常依赖于手工制作的数据集级别的经验分布先验，如[45]中的颜色掩码和[47]中的语义-颜色映射，这些都是繁琐且难以推广的。

在本文中，我们提出了一种新颖的上色方法，即DDColor，旨在实现语义合理且视觉生动的上色。我们的方法利用了一个编码器-解码器结构，其中编码器提取图像特征，双解码器恢复空间分辨率。与先前方法采用额外网络或手工计算的先验来优化颜色概率不同，我们的方法使用基于查询的Transformer作为颜色解码器，以端到端的方式学习语义感知的颜色查询。通过使用多尺度图像特征进行颜色查询学习，我们的方法显着减轻了颜色晕染，并显着改善了复杂上下文和小物体的着色（见图1）。此外，我们提出了一种新的色彩度损失，以提高生成结果的颜色丰富度。

我们的主要贡献总结如下：

- 我们提出了一种带有双解码器的端到端网络，用于自动图像上色，确保了生动且语义一致的结果。
- 我们的方法包括一种新颖的颜色解码器，从视觉特征中学习颜色查询而无需依赖手工制作的先验。此外，我们的像素解码器提供多尺度语义表示来指导颜色查询的优化，有效减少了颜色晕染效应。
- 综合实验表明，我们的方法在与基线相比实现了最先进的性能，并表现出良好的泛化能力。


![image.png](/static/img/f3379daf7f584a6f6a95ece7762f96db.image.webp)

## 3. 方法

### 3.1 概述

给定一个灰度输入图像 $x_L \in \mathbb{R}^{H \times W \times 1}$，我们的上色网络预测缺失的两个颜色通道 $\hat{y}_{AB} \in \mathbb{R}^{H \times W \times 2}$，其中 $L, AB$ 通道分别表示在 CIELAB 色彩空间中的明度和色度。网络采用编码器-解码器框架，如图2（a）所示。

我们利用一个backbone network作为编码器，从灰度图像中提取高级语义信息。backbone network旨在提取图像语义嵌入，这是上色视频化的关键。在本研究中，我们选择ConvNeXt [29]，这是用于图像分类的最前沿模型。以 $x_L$ 作为输入，backbone network 输出4个分辨率为 $\frac{H}{4} \times \frac{W}{4}$、$\frac{H}{8} \times \frac{W}{8}$、$\frac{H}{16} \times \frac{W}{16}$ 和 $\frac{H}{32} \times \frac{W}{32}$ 的中间特征图。前三个特征图通过快捷连接传递到pixel decoder，而最后的特征图作为pixel decoder的输入。至于backbone network的结构，有几种选择，比如 ResNet[17]、Swin-Transformer[28] 等，只要网络能够生成分层表示。

我们的框架的解码器部分由像素解码器和色彩解码器组成。像素解码器使用一系列堆叠的上采样层来恢复图像特征的空间分辨率。每个上采样层与编码器的相应阶段有快捷连接。色彩解码器利用多尺度图像特征逐渐优化基于语义的颜色查询。最后，由两个解码器生成的图像和颜色特征融合生成彩色输出。

在接下来的部分中，我们将详细描述这些模块以及用于上色视频化的损失函数。

### 3.2 双重解码器

#### 3.2.1 像素解码器

像素解码器由四个阶段组成，逐步扩大图像分辨率。每个阶段包括一个上采样层和一个快捷层。具体来说，不同于以前的方法使用反卷积 [34] 或插值 [30]，我们采用 PixelShuffle [37] 作为上采样层。该层将形状为 $(h_p, w_p, \frac{c_p}{2})$ 的低分辨率特征图重新排列为形状为 $(h, w, c)$ 的高分辨率特征图。快捷层使用卷积通过快捷连接整合来自编码器相应阶段的特征。

我们的方法通过逐步上采样过程捕获了完整的图像特征金字塔，这超出了某些基于transformer方法的能力 [24, 45]。这些多尺度特征进一步用作色彩解码器的输入，以指导颜色查询的优化。像素解码器的最终输出是图像嵌入 $E_i \in \mathbb{R}^{C \times H \times W}$，其空间分辨率与输入图像相同。

#### 3.2.2 色彩解码器

许多现有的上色视频化方法依赖于额外的先验来实现生动的结果。例如，一些方法 [46, 13] 利用来自预训练的GAN的生成先验，而其他方法使用经验分布统计 [45] 或训练集的预构建语义-颜色对 [47]。然而，这些方法需要大量的预构建工作，并且在各种场景中可能具有有限的适用性。为了减少对手动设计先验的依赖，我们提出了一种新颖的基于查询的色彩解码器。

**色彩解码器块**。色彩解码器由一堆块组成，每个块接收视觉特征和颜色查询作为输入。色彩解码器块（CDB）基于修改过的transformer解码器设计，如图2（b）所示。

为了基于视觉语义信息学习一组自适应颜色查询，我们创建可学习的色彩嵌入记忆，以存储颜色表示序列：
$$
Z_0 = [Z^1_0, Z^2_0, \dots, Z^K_0] \in \mathbb{R}^{K \times C}
$$
这些颜色嵌入在训练阶段初始化为零，并在第一个CDB中用作颜色查询。我们首先通过cross-attention层建立语义表示与颜色嵌入之间的关联：
$$
Z^{\prime}_l = \text{softmax}(Q_l K^T_l)V_l + Z_{l-1},
$$
其中 $l$ 是层索引，$Z_l \in \mathbb{R}^{K \times C}$ 是第 $l$ 层的 $K$ 维颜色嵌入。$Q_l = f_Q(Z_{l-1}) \in \mathbb{R}^{K \times C}$，$K_l, V_l \in \mathbb{R}^{H_l \times W_l \times C}$ 是图像特征，它们经过 $f_K(\cdot)$ 和 $f_V(\cdot)$ 变换，分别表示。$H_l$ 和 $W_l$ 是图像特征的空间分辨率，$f_Q$, $f_K$, 和 $f_V$ 是线性变换。

通过上述cross-attention操作，颜色嵌入表示由图像特征丰富。然后，我们利用标准transformer层来变换颜色嵌入，如下：
$$
Z^{\prime\prime}_l = \text{MSA}(\text{LN}(Z^{\prime}_l)) + Z^{\prime}_l,
$$
$$
Z^{\prime\prime\prime}_l = \text{MLP}(\text{LN}(Z^{\prime\prime}_l)) + Z^{\prime\prime}_l,
$$
$$
Z_l = \text{LN}(Z^{\prime\prime\prime}_l),
$$
其中 $\text{MSA}(\cdot)$ 表示multi-head self-attention [42]，$\text{MLP}(\cdot)$ 表示前馈网络，$\text{LN}(\cdot)$ 是层归一化 [3]。值得注意的是，在所提出的CDB中，cross-attention在self-attention之前进行。这是因为在应用第一个self-attention层之前，颜色查询是零初始值且语义上独立。

**扩展到多尺度**。以前基于transformer的上色视频化方法通常在单一尺度图像特征图上执行颜色关注，未能充分捕捉低级语义线索，在处理复杂背景时可能导致颜色渗出。相反，多尺度特征已在许多计算机视觉任务中广泛探索，如物体检测 [26] 和实例分割 [16]。这些特征也可以提升上色的性能（详见Sec 4.3中的对比实验）。

为了平衡计算复杂度和表示能力，我们选择了三种不同尺度的图像特征。具体来说，我们使用pixel decoder生成的中间视觉特征，在色彩解码器中使用1/16、1/8和1/4的下采样率。我们将每组的3个CDB分组，在每组中，多尺度特征按顺序输入到CDB中。我们以轮转方式重复此组M次。总共，色彩解码器由3M个CDB组成。我们可以将色彩解码器公式化如下：
$$
E_c = \text{ColorDecoder}(Z_0, F_1, F_2, F_3),
$$
其中 $F_1, F_2$ 和 $F_3$ 是三种不同尺度的视觉特征。

在色彩解码器中使用多尺度特征可以建模颜色查询与视觉嵌入之间的关系，使得颜色嵌入$E_c \in \mathbb{R}^{K \times C}$对语义信息更敏感，进一步实现更准确的语义边界识别和减少颜色渗出。

### 3.3 融合模块

融合模块是一个轻量级模块，通过结合像素解码器和色彩解码器的输出生成彩色结果。如图2所示，融合模块的输入为每像素图像嵌入 $E_i \in \mathbb{R}^{C \times H \times W}$，其中 $C$ 是嵌入维度，以及来自色彩解码器的语义感知颜色嵌入 $E_c \in \mathbb{R}^{K \times C}$，其中 $K$ 是颜色查询的数量。

融合模块将这两个嵌入聚合形成增强的特征 $\hat{F} \in \mathbb{R}^{K \times H \times W}$，使用一个简单的点积。然后应用一个 $1 \times 1$ 卷积层生成最终输出 $\hat{y}_{AB} \in \mathbb{R}^{2 \times H \times W}$，其表示AB颜色通道：
$$
\hat{F} = E_c \cdot E_i,
$$
$$
\hat{y}_{AB} = \text{Conv}(\hat{F}).
$$
最后，通过将输出 $\hat{y}_{AB}$ 与灰度输入 $x_L$ 拼接，获得上色结果 $\hat{y}$。

### 3.4 目标

在训练阶段，采用以下四种损失：

**像素损失**。像素损失 $L_{\text{pix}}$ 是上色图像 $\hat{y}$ 和真实图像 $y$ 之间的L1距离，提供像素级监督并鼓励生成类似于真实图像的输出。

**感知损失**。为了确保生成的图像 $\hat{y}$ 在语义上合理，我们使用感知损失 $L_{\text{per}}$ 来最小化它与真实图像 $y$ 之间的语义差异。这是通过使用预训练的 VGG16 [38] 从两个图像中提取特征来实现的。

**对抗损失**。添加一个 PatchGAN [23] 判别器来区分预测结果和真实图像，促使生成器生成无法区分的图像。令 $L_{\text{adv}}$ 表示对抗损失。

**色彩丰富度损失**。我们引入了一种新的色彩丰富度损失 $L_{\text{col}}$ ，其灵感来源于色彩丰富度分数 [15]。该损失鼓励模型生成更加丰富和视觉愉悦的图像。公式如下：
$$
L_{\text{col}} = 1 - [\sigma_{\text{rgyb}} (\hat{y}) + 0.3 \cdot \mu_{\text{rgyb}} (\hat{y})]/100,
$$
其中 $\sigma_{\text{rgyb}} (\cdot)$ 和 $\mu_{\text{rgyb}} (\cdot)$ 分别表示颜色平面中像素云的标准差和均值，如 [15] 中所述。

生成器的全目标公式如下：
$$
L_{\theta} = \lambda_{\text{pix}} L_{\text{pix}} + \lambda_{\text{per}} L_{\text{per}} + \lambda_{\text{adv}} L_{\text{adv}} + \lambda_{\text{col}} L_{\text{col}},
$$
其中 $\lambda_{\text{pix}}, \lambda_{\text{per}}, \lambda_{\text{adv}}$ 和 $\lambda_{\text{col}}$ 是不同项的平衡权重。

DDColor 通用场景黑白图片上色 论文点

# 基于pix2pix的图像彩色化技术实践与探索

## 一、项目背景与问题发现

在前期实验中，我尝试使用mmgen库进行通用图像和线稿的处理，但效果不尽如人意。这让我开始怀疑mmgen库在此类任务中的适用性。经过评估后，我决定转向另一个成熟的解决方案。



## 二、技术方案选型

### 2.1 选定仓库
最终选择的实现方案来自以下GitHub仓库：
```bash
git@github.com:junyanz/pytorch-CycleGAN-and-pix2pix.git
```

### 2.2 环境配置
采用Docker容器搭建训练环境，具体配置如下：
```bash
docker run --gpus all --shm-size=32g -it --net host \
-v ./pytorch-CycleGAN-and-pix2pix/:/pytorch-CycleGAN-and-pix2pix/ \
-v ./anime-sketch-colorization-pair/data:/data \
pytorch/pytorch:2.5.1-cuda12.1-cudnn9-devel bash

pip install -r requirements.txt
```

为方便后续使用，已将配置好的环境保存为镜像：
```bash
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-pix2pix
```

直接使用命令：
```bash
docker run --gpus all --shm-size=32g -it --net host \
-v ./pytorch-CycleGAN-and-pix2pix/:/pytorch-CycleGAN-and-pix2pix/ \
-v ./anime-sketch-colorization-pair/data:/data \
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-pix2pix bash
```

## 三、训练过程实录

### 3.1 基础训练配置
首先启动visdom可视化服务器：
```bash
python -m visdom.server -p 8097
```

采用以下两种训练方式之一：

**基础训练命令**：
```bash
python train.py --dataroot /data/ --name anime --gpu_ids 0,1,2,3 \
--model pix2pix --direction BtoA --batch_size 192 --lr_policy cosine \
--num_threads 32 --init_type xavier --norm instance --netG unet_256
```

**带visdom监控的训练**：
```bash
-display_server http://remote_ip --display_port 8097
```

通过浏览器访问8097端口可查看训练效果：

![训练监控界面](/static/img/b2c0b87baed3e8d6830533fff36432c2.image.webp)

### 3.2 初步训练结果
经过200轮训练后，效果仍有提升空间：

![200轮训练效果](/static/img/eecec56cf99c304d7d8785d7b802d02b.image.webp)

## 四、优化后的彩色化方案

### 4.1 技术原理突破
深入研究后发现更优的彩色化方法：输入单通道黑白图，输出为LAB色彩空间中的AB通道。

### 4.2 改进训练配置
```bash
cd /ssd/xiedong/image_color

docker run --gpus all --shm-size=32g -it --net host \
-v ./pytorch-CycleGAN-and-pix2pix/:/pytorch-CycleGAN-and-pix2pix/ \
-v ./unpaired_self_datasets/:/data \
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-pix2pix bash

nohup python -m visdom.server -p 8097 &

pip install -U scikit-image

cd /pytorch-CycleGAN-and-pix2pix/

python train.py \
  --dataroot /data/ \
  --name tongyong_l2ab_4 \
  --gpu_ids 0,1,2 \
  --model colorization \
  --direction AtoB \
  --batch_size 196 \
  --lr_policy cosine \
  --num_threads 32 \
  --init_type xavier \
  --norm instance \
  --netG unet_256 \
  --dataset_mode colorization \
  --input_nc 1 \
  --output_nc 2 \
  --phase trainA \
  --n_epochs 100
```

训练后可以绘制损失变化图：

python plot_loss_paper.py


![colorization_loss_curves.png](/static/img/40a8b5efdd26bed6115abd977c27b6ff.colorization_loss_curves.webp)



### 4.3 数据处理流程
• 系统自动将RGB图像转换为Lab色彩空间
• 分离L通道（亮度）作为输入
• 提取ab通道（色彩）作为输出目标
• 转换过程在ColorizationDataset类中自动完成

### 4.4 训练效果展示
**验证集输入（valA）**：
![灰度输入示例](/static/img/8aa1695fbb5229c8107b28c73e1f0940.zooh_002539.webp)

**验证集目标（valB）**：
![真实色彩示例](/static/img/70d1d6d87b64552cc33ce945c49f88da.zooh_002539.webp)

**生成效果对比**：
![色彩化效果对比](/static/img/e0ee6e095bbb41f82f83f6180527b291.image.webp)

训练完成的模型保存在：
```
pytorch-CycleGAN-and-pix2pix/checkpoints
```

## 五、技术参数详解

### 5.1 核心训练参数说明

#### 基础配置
| 参数 | 说明 | 示例值 |
|------|------|--------|
| `--dataroot` | 数据根目录 | `/data/` |
| `--name` | 实验名称 | `tongyong_l2ab_4` |
| `--gpu_ids` | 使用的GPU编号 | `0,1,2` |

#### 模型架构
| 参数 | 说明 | 可选值 |
|------|------|--------|
| `--model` | 模型类型 | `colorization` |
| `--netG` | 生成器架构 | `unet_256` |
| `--norm` | 归一化方法 | `instance` |

#### 训练策略
| 参数 | 说明 | 典型值 |
|------|------|--------|
| `--lr_policy` | 学习率策略 | `cosine` |
| `--batch_size` | 批次大小 | `196` |
| `--n_epochs` | 训练周期数 | `100` |

### 5.2 训练日志解析
典型训练日志示例：
```
(epoch: 39, iters: 115800, time: 0.007, data: 0.044) 
G_GAN: 2.019 G_L1: 8.129 D_real: 0.409 D_fake: 0.279
```

#### 指标说明
1. **G_GAN**：生成器对抗损失，反映生成器欺骗判别器的能力
2. **G_L1**：生成器L1损失，衡量色彩预测准确性
3. **D_real**：判别器对真实样本的识别能力
4. **D_fake**：判别器对生成样本的识别能力

#### 数学表达
• 生成器总损失：$\mathcal{L}_G = \mathcal{L}_{GAN} + \lambda\mathcal{L}_{L1}$
• 判别器总损失：$\mathcal{L}_D = \frac{1}{2}(\mathcal{L}_{real} + \mathcal{L}_{fake})$

## 六、技术原理深入

### 6.1 色彩空间理论
采用CIE Lab色彩空间，其中：
- • L通道：亮度信息（0-100）
- • a通道：绿(-128)到红(+127)色度
- • b通道：蓝(-128)到黄(+127)色度

### 6.2 网络架构
#### 生成器设计
U-Net结构包含：
1. 编码器路径：8级下采样
2. 解码器路径：对应上采样
3. 跳跃连接：保留细节信息

#### 判别器设计
采用PatchGAN架构：
- • 局部感受野：70×70像素
- • 输出特征图：$\frac{H}{n}×\frac{W}{n}$

### 6.3 训练优化
- • 数据增强：随机裁剪/翻转
- • 归一化处理：L通道→[-1,1]，ab通道→[-1,1]
- • 损失权重：$\lambda=100$

## 七、应用与验证

### 7.1 测试方法

要测试您训练好的模型（第35轮）使用您在"/data/testA"的测试数据，您应该在服务器上运行以下命令：

```
python test.py --dataroot /data/ --name tongyong_l2ab_4 --model colorization --direction AtoB --netG unet_256 --dataset_mode colorization --input_nc 1 --output_nc 2 --phase testA --epoch 35 --eval --num_test 500 --norm instance
```

如果想处理数据集中的所有图像，您需要将num_test设置为一个足够大的数字，确保它大于数据集中的图像总数。


结果会被保存到：results/tongyong_l2ab_4/testA_35/images/

此命令将：
1. 从第35轮加载您的模型检查点
2. 处理来自testA目录的图像
3. 生成着色结果
4. 将结果保存到HTML网页以便进行视觉检查

关键参数说明：
- `--dataroot /data/`：数据目录的路径
- `--name tongyong_l2ab_4`：您的实验名称（与训练名称匹配）
- `--model colorization`：使用着色模型
- `--netG unet_256`：使用与训练相同的生成器架构
- `--input_nc 1 --output_nc 2`：与您的训练设置相同（L到ab颜色空间）
- `--phase testA`：使用testA目录进行测试
- `--epoch 35`：从第35轮加载模型
- `--eval`：在评估模式下运行（禁用dropout）
- `--num_test 500`：测试多达500张图像（您可以调整这个数字）

#### 修改几句代码才行

报错了，需要改几句代码：

对于 PyTorch 2.5 版本，您需要修改服务器上的代码。服务器上的 `load_networks` 函数中有两个不兼容的参数：

1. `weights_only=True` - 这是较新版本的 PyTorch 引入的参数
2. `strict=False` - 这个参数应该传递给 `load_state_dict` 而不是 `torch.load`

因此，正确的修改方案是：

1. 在服务器上编辑 `models/base_model.py` 文件
2. 找到 `load_networks` 函数中的这一行：

```python
state_dict = torch.load(load_path, weights_only=True, map_location=self.device, strict=False)
```

3. 将其修改为：

```python
state_dict = torch.load(load_path, map_location=str(self.device))
```

4. 如果您需要保留 `strict=False` 的功能，则需要修改后面的 `load_state_dict` 调用：

```python
net.load_state_dict(state_dict, strict=False)
```

这样修改后应该可以与 PyTorch 2.5 兼容，同时保持原有功能。

5. 其他介绍：


weights_only=True 参数

- 功能：这是PyTorch较新版本(2.0+)引入的参数，用于只加载模型的权重部分，而不加载优化器状态、学习率调度器等其他存储在模型文件中的信息。
- 作用：当您只需要模型权重而不需要恢复训练状态时，此参数可以节省内存并加快加载速度。

map_location=self.device vs map_location=str(self.device)

- 旧版本PyTorch(0.4之前)需要字符串形式，而较新版本既可以接受torch.device对象也可以接受字符串。

strict=False 参数
- 功能：strict参数控制在加载模型时如何处理键不匹配的情况。
- 关键点：在您修改前的代码中，strict=False被错误地放在了torch.load()调用中，而它应该属于后续的load_state_dict()调用。

#### testA目录

testA目录 里应该是彩色的图片，ColorizationDataset 类里会进行这样的处理：

```python
def __getitem__(self, index):
    path = self.AB_paths[index]
    im = Image.open(path).convert('RGB')  # <-- 打开图像并转换为RGB
    im = self.transform(im)
    im = np.array(im)
    lab = color.rgb2lab(im).astype(np.float32)  # <-- 将RGB转换为Lab
    lab_t = transforms.ToTensor()(lab)
    A = lab_t[[0], ...] / 50.0 - 1.0  # <-- 提取L通道（灰度）
    B = lab_t[[1, 2], ...] / 110.0  # <-- 提取ab通道（色彩）
    return {'A': A, 'B': B, 'A_paths': path, 'B_paths': path}
```

### 7.2 效果评估
通过定期验证集测试监控训练进展，关键步骤：
1. 反归一化处理
2. Lab→RGB转换
3. 生成效果可视化对比


## 八、评估指标


- SSIM (结构相似性): 这是一个广泛使用的指标，衡量两幅图像在结构上的相似度。值范围从0到1，越高越好。SSIM>0.85通常被认为是高质量的结果。
- PSNR (峰值信噪比): 这个指标衡量的是图像重建的质量，单位为dB。通常，PSNR>30dB被认为是高质量的。在着色任务中，25-35dB通常是好的结果。
- 色彩误差: 这是我专门为着色任务添加的指标，它衡量Lab色彩空间中ab通道的平均绝对误差。这个指标直接评估了着色的准确性，而不仅仅是整体图像相似度。
- LPIPS (感知相似度): 这是一个基于深度学习的感知相似度度量，更符合人类对图像质量的判断。值越低表示感知上越相似。
- FID (Fréchet Inception Distance): 这个指标衡量生成图像的分布与真实图像分布之间的距离。它使用Inception网络提取特征，并计算特征空间中的分布差异。FID值越低越好，通常<20被认为是高质量的生成结果。

在第七章节后，我们获取到了结果图：./results/tongyong_l2ab_4/testA_35/images/

每三个图是一组，比如：
```bash
-rw-r--r-- 1 root root 134573 Apr 10 02:17 002_trafficScene_youxian1_000020_fake_B_rgb.png
-rw-r--r-- 1 root root 132559 Apr 10 02:17 002_trafficScene_youxian1_000020_real_B_rgb.png
-rw-r--r-- 1 root root  86333 Apr 10 02:17 002_trafficScene_youxian1_000020_real_A.png
```

real_A 是黑白图，real_B_rgb 是真实的RGB图，fake_B_rgb 是模型根据real_A进行上色得到的图。

指标就是为了评估fake_B_rgb是否能接近real_B_rgb。

为了得到评估指标，需要给容器里安装点环境：


```
apt update && apt install -y libgl1

pip install -r evaluation_requirements.txt # 在我自己的github项目里
```
运行评估脚本：


```bash
# 基本版本
python evaluate_basic.py --results_dir ./results/tongyong_l2ab_4/testA_35/images --output_dir ./evaluation_basic_results

# 完整版本
python evaluate_colorization.py --results_dir ./results/tongyong_l2ab_4/testA_35/images --output_dir ./evaluation_results

# 完整版本 带FID指标
python evaluate_colorization.py --results_dir ./results/tongyong_l2ab_4/testA_35/images --output_dir ./evaluation_results --use_fid
```

得到：

| Metric            | Mean      | Std       | Min       | Max        |
|-------------------|-----------|-----------|-----------|------------|
| SSIM             | 0.892293  | 0.087055  | 0.496115  | 0.991259   |
| PSNR             | 22.315565 | 4.723317  | 9.698197  | 36.125977  |
| MSE              | 682.852914| 889.681447| 15.866557 | 6970.447413|
| MAE              | 15.264377 | 9.815629  | 1.971761  | 66.205879  |
| Color Error      | 11.004399 | 7.5067    | 1.517296  | 51.797058  |
| LPIPS            | 0.193544  | 0.092814  | 0.009559  | 0.553977   |
| FID              | 49.714922 | -         | -         | -          |

模型表现不错：
- SSIM平均值: 0.892 - 非常好，接近0.9意味着生成的图像与真实图像结构相似度很高
- PSNR平均值: 22.32 dB - 对于着色任务来说是合理的值
- Color Error平均值: 11.00 - 这是在Lab色彩空间中ab通道的误差
- LPIPS平均值: 0.194 - 表示感知相似度较好（越低越好）
- FID值是49.714922，这属于中等性能水平：
FID值越低越好，表示生成分布与真实分布越接近
通常FID < 20被视为非常好
FID在20-50之间被视为可接受
FID > 100通常表示生成质量较差


## 九、WebUI部署

启动web服务：

```
python colorization_app.py
```

网页前端使用：

![image.png](/static/img/7dc7df3b35d0acf2164d3e6b7384b789.image.webp)

## 十、其他理论

### U-Net生成器

我们的彩色化模型采用U-Net[4]作为生成器的骨干网络。U-Net是一种编码器-解码器结构，增加了跳跃连接(skip connection)以保留细节信息。对于彩色化任务，我们采用unet_256变体，具有8个下采样层。

U-Net生成器的结构可以表示为：

$$G: \mathbb{R}^{H \times W \times 1} \rightarrow \mathbb{R}^{H \times W \times 2}$$

具体而言，它由以下部分组成：
1. **编码器路径**：通过一系列卷积层和下采样操作将输入从 $H \times W \times 1$ 逐渐降维到 $\frac{H}{256} \times \frac{W}{256} \times 512$
2. **解码器路径**：通过上采样和反卷积操作将特征图从 $\frac{H}{256} \times \frac{W}{256} \times 512$ 恢复到 $H \times W \times 2$
3. **跳跃连接**：在对应的编码器和解码器层之间建立直接连接，帮助网络保留边缘和细节信息

具体的数学表示为：

$$h_i = \text{Down}(h_{i-1}), i \in [1, 8]$$
$$h'_i = \text{Up}(h'_{i+1}, h_i), i \in [7, 0]$$

其中 $\text{Down}(\cdot)$ 表示下采样操作，$\text{Up}(\cdot, \cdot)$ 表示上采样与特征连接操作，$h_0$ 是输入的L通道，$h'_0$ 是输出的ab通道预测。

###  PatchGAN判别器

我们使用PatchGAN作为判别器，它仅关注局部图像块(patch)的真实性而非整体图像，这有助于保持色彩的局部一致性和纹理细节。PatchGAN判别器可以表示为：

$$D: \mathbb{R}^{H \times W \times 3} \rightarrow \mathbb{R}^{\frac{H}{n} \times \frac{W}{n} \times 1}$$

其中输入是L通道与ab通道（真实或生成）的拼接，输出是一个 $\frac{H}{n} \times \frac{W}{n}$ 的评分图，每个位置对应一个感受野为 $70 \times 70$ 的图像区域。判别器包含5个卷积层，中间使用实例归一化(Instance Normalization)和LeakyReLU激活函数。

### 损失函数

在训练过程中，网络同时优化两个损失函数：
1. **条件GAN损失**：$\mathcal{L}_{cGAN}(G, D)$，促使生成的色彩在局部区域看起来逼真
2. **L1距离损失**：$\mathcal{L}_{L1}(G)$，确保生成的色彩与真实色彩的整体一致性

对于判别器 $D$，我们使用标准的GAN判别器损失：

$$\mathcal{L}_D = \frac{1}{2}\mathbb{E}_{x,y}[(D(x, y) - 1)^2] + \frac{1}{2}\mathbb{E}_{x}[D(x, G(x))^2]$$

对于生成器 $G$，我们结合GAN损失和L1损失：

$$\mathcal{L}_G = \mathbb{E}_{x}[(D(x, G(x)) - 1)^2] + \lambda \mathbb{E}_{x,y}[\|y - G(x)\|_1]$$

其中，我们设置 $\lambda = 100$ 来强调色彩的准确性。


## 十一、镜像，代码，权重

镜像环境安装了一些别的，新的镜像名称为：`kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-pix2pix-webui`


代码仓库：https://github.com/xxddccaa/pytorch-CycleGAN-and-pix2pix-color#


webui启动：

```bash
cd /ssd/xiedong/image_color

docker run --gpus device=2 --shm-size=32g -it --net host \
-v ./pytorch-CycleGAN-and-pix2pix/:/pytorch-CycleGAN-and-pix2pix/ \
-v ./unpaired_self_datasets/:/data \
kevinchina/deeplearning:2.5.1-cuda12.1-cudnn9-devel-pix2pix-webui bash

cd /pytorch-CycleGAN-and-pix2pix

python colorization_app.py
```

pix2pix pytorch 图片上色，模型训练实战，Docker【3】

通用场景上色任务太难，pix2pix效果不佳：

https://www.dong-blog.fun/post/1924


通用场景照片的要求太大了：要场景、要渐变色、要理解场景里的事物，比如你总不能给树叶上一个红色，是需要一定语义理解能力的。

线稿是一种需要块状涂色的任务，相对就简单得多。



这是线稿任务：

![image.png](/static/img/6b020899caa348a019213124922eb38d.image.webp)

## 数据集
https://www.kaggle.com/datasets/ktaebum/anime-sketch-colorization-pair

下载这个数据集：

```
import kagglehub

# Download latest version
path = kagglehub.dataset_download("ktaebum/anime-sketch-colorization-pair")

print("Path to dataset files:", path)
```

## 训练

```
docker run --gpus all --shm-size=16g -it --net host \
-v /ssd/xiedong/image_color/anime-sketch-colorization-pair/data:/mmgen/data \
-v ./pretrain:/mmgen/pretain \
-v ./work_dirs:/mmgen/work_dirs \
kevinchina/deeplearning:mmgenerationv1-addtb bash

vim configs/pix2pix/pix2pix_vanilla_unet_bn_facades_b1x1_80k.py

export OMP_NUM_THREADS=8
export MKL_NUM_THREADS=8
export CONFIG_FILE=configs/pix2pix/pix2pix_vanilla_unet_bn_facades_b1x1_80k.py
export GPUS_NUMBER=4
export WORK_DIR=./work_dirs/pix2pix_xiangao
bash tools/dist_train.sh ${CONFIG_FILE} ${GPUS_NUMBER} \
    --work-dir ${WORK_DIR} 


# 宿主机可以看日志
tensorboard --logdir="tf_logs/" --bind_all
```

配置写：

```
_base_ = [
    '../_base_/models/pix2pix/pix2pix_vanilla_unet_bn.py',
    '../_base_/datasets/paired_imgs_256x256_crop.py',
    '../_base_/default_runtime.py'
]
source_domain = 'mask'
target_domain = 'photo'
# model settings
model = dict(
    default_domain=target_domain,
    reachable_domains=[target_domain],
    related_domains=[target_domain, source_domain],
    gen_auxiliary_loss=dict(
        data_info=dict(
            pred=f'fake_{target_domain}', target=f'real_{target_domain}')))

# dataset settings
domain_a = target_domain
domain_b = source_domain
img_norm_cfg = dict(mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5])
train_pipeline = [
    dict(
        type='LoadPairedImageFromFile',
        io_backend='disk',
        key='pair',
        domain_a=domain_a,
        domain_b=domain_b,
        flag='color'),
    dict(
        type='Resize',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        scale=(286, 286),
        interpolation='bicubic'),
    dict(
        type='FixedCrop',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        crop_size=(256, 256)),
    dict(
        type='Flip',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        direction='horizontal'),
    dict(type='RescaleToZeroOne', keys=[f'img_{domain_a}', f'img_{domain_b}']),
    dict(
        type='Normalize',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        to_rgb=False,
        **img_norm_cfg),
    dict(type='ImageToTensor', keys=[f'img_{domain_a}', f'img_{domain_b}']),
    dict(
        type='Collect',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        meta_keys=[f'img_{domain_a}_path', f'img_{domain_b}_path'])
]
test_pipeline = [
    dict(
        type='LoadPairedImageFromFile',
        io_backend='disk',
        key='pair',
        domain_a=domain_a,
        domain_b=domain_b,
        flag='color'),
    dict(
        type='Resize',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        scale=(256, 256),
        interpolation='bicubic'),
    dict(type='RescaleToZeroOne', keys=[f'img_{domain_a}', f'img_{domain_b}']),
    dict(
        type='Normalize',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        to_rgb=False,
        **img_norm_cfg),
    dict(type='ImageToTensor', keys=[f'img_{domain_a}', f'img_{domain_b}']),
    dict(
        type='Collect',
        keys=[f'img_{domain_a}', f'img_{domain_b}'],
        meta_keys=[f'img_{domain_a}_path', f'img_{domain_b}_path'])
]

dataroot = 'data'
data = dict(
    train=dict(dataroot=dataroot, pipeline=train_pipeline),
    val=dict(dataroot=dataroot, pipeline=test_pipeline),
    test=dict(dataroot=dataroot, pipeline=test_pipeline))

# optimizer
optimizer = dict(
    generators=dict(type='Adam', lr=2e-4, betas=(0.5, 0.999)),
    discriminators=dict(type='Adam', lr=2e-4, betas=(0.5, 0.999)))

# learning policy
lr_config = None

# checkpoint saving
checkpoint_config = dict(interval=50000, save_optimizer=True, by_epoch=False)
custom_hooks = [
    dict(
        type='MMGenVisualizationHook',
        output_dir='training_samples',
        res_name_list=[f'fake_{target_domain}'],
        interval=5000)
]
runner = None
use_ddp_wrapper = True

# runtime settings
total_iters = 1000000
workflow = [('train', 1)]
exp_name = 'pix2pix_xian_gao'
work_dir = f'./work_dirs/{exp_name}'
num_images = 5000
metrics = dict(
    FID=dict(type='FID', num_images=num_images, image_shape=(3, 256, 256)),
    IS=dict(
        type='IS',
        num_images=num_images,
        image_shape=(3, 256, 256),
        inception_args=dict(type='pytorch')))

# evaluation = dict(
#     type='TranslationEvalHook',
#     target_domain=domain_b,
#     interval=10000,
#     metrics=[
#         dict(type='FID', num_images=num_images, bgr2rgb=True),
#         dict(
#             type='IS',
#             num_images=num_images,
#             inception_args=dict(type='pytorch'))
#     ],
#     best_metric=['fid', 'is'])

# 日志配置信息
log_config = dict(
    interval=10,  # 打印日志的间隔， 单位 iters
    hooks=[
        dict(type='TextLoggerHook'),  # 用于记录训练过程的文本记录器(logger)
        dict(type='TensorboardLoggerHook')  # 同样支持 Tensorboard 日志
    ])
# yapf:enable
log_level = 'INFO'  # 日志的输出级别
```

这个任务显然是简单一些，loss很快就降低了：

![image.png](/static/img/89781b5b104b8138d2a48e2bf581d4f4.image.webp)

## 推理


```
python demo/translation_demo.py \
    'configs/pix2pix/pix2pix_vanilla_unet_bn_facades_b1x1_80k.py' \
    /mmgen/work_dirs/pix2pix_xiangao/ckpt/pix2pix_xiangao/latest.pth \
    'data/test/984079.png' \
    --save-path work_dirs/demo.png
```


![image.png](/static/img/619db50bf30d40f6a3fb0d0626375ec6.image.webp)

效果还是不好，换个框架再试试，这个mmgeneration 是不是有毒：

![image.png](/static/img/7190a3af745088a22f10b3af11cbc125.image.webp)