手上的红米 K40S 已经服役了 3 年多， 从 MIUI 12 升级到 MIUI 13， 再到现在的 HyperOS 1.0 (Android 14)， 官方的系统支持肯定是结束了， 在更换手机或者转为备用机之前，还想继续折腾一下， 当然也有其它几个方面的原因，一并说明如下：

1. 官方系统停止更新，止步于 HyperOS 1.0 (Android 14)；
2. 官方系统臃肿， 而且广告很多， 而且有些广告还去不掉；
3. 安装第三方 apk ， 时不时跳出验证， 体验非常糟糕；
4. LineageOS 官方支持 K40S， 目前是 LineageOS 22.2 (Android 15) ， 很大可能也会有 LineageOS 23 (Android 16) ；
5. 时隔多年想再体验下类原生安卓系统；

鉴于以上几点原因， 准备将 K40S 解锁并安装 LineageOS 。

解锁 Bootloader

现在小米刷类原生安卓系统最大的障碍就是解锁 Bootloader ，随着 HyperOS 的发布， 小米旗下机型解锁的难度越来越高， 令不少人都望而却步。 不出意外， 这部 K40S 将是我的最后一部小米手机， 后续机型不能解锁 Bootloader 的话， 将不会再购买小米的任何手机。

引用 GitHub 上大佬 MlgmXyysd 的话，那就是： 自从小米限制解锁 BootLoader 后，小米就一直在违背”极客”精神，甚至违背了 GPL。 原文链接

幸好， 在 github 上有一些开源的项目可以绕过小米 HyperOS 对 BootLoader 解锁账户绑定限制社区等级的 PoC ， 它们是：

• Xiaomi-HyperOS-BootLoader-Bypass
• HyperSploit

只要出厂是 MIUI 的手机， 一般都可以借助这两个软件成功解锁。 比较了这两个软件， 我选择的是 HyperSploit ， 因为使用起来更加简单， 不用折腾 PHP 。

解锁的过程很顺利， 简单罗列如下：

1. 需要一台 Windows 电脑， 安装小米官方的手机驱动程序；
2. 打开 ADB 调试模式并授权电脑调试；
3. 开发者模式界面根据提示绑定账号；
4. 运行 HyperSploit ，根据提示进行操作即可；

虽然 HyperSploit 有 macOS 版本， 我尝试了一下，没有达到预期目标， 只好用另一台 Windows 电脑进行操作。

具体可以查看这里的 前置要求 和 使用教程 ， 这两个软件的用法基本上是相同的。

幸运的是， 我的小米帐号没有被封控， 绑定到 K40S 之后， 只要等7天就可以顺利解锁。

解锁成功之后， 就可以开始安装 LineageOS 了。

安装 LineageOS

升级固件版本

在正式安装 LineageOS 之前，需要确认手机的固件版本， 如果不是最新版的话， 需要先升级到最新版， 否则安装 LineageOS 可能会失败。 目前 LineageOS 支持的 K40S 固件版本为 OS1.0.2.0.ULMCNXM ，如果是这个版本的话， 可以根据 LineageOS 的固件升级指南升级下固件。

所谓的固件 (Firmware) 也就是手机硬件的驱动程序， LineageOS 依赖官方镜像的固件驱动程序才能正常运行。

我记得以前的固件是直接包含在 LineageOS 固件中的， 现在不知什么原因，需要单独下载了，不过这些对于要刷机的人来说， 根本都不是事儿。

刷固件相当于装驱动， 对手机内的数据没有任何影响，因此可以放心刷， 步骤如下：

下载官方镜像

• 从 MIUI 官方网站下载 K40S 的完整安装镜像 OS1.0.2.0.ULMCNXM
• 下载完成之后得到的文件为 miui_MUNCH_OS1.0.2.0.ULMCNXM_6438305cc0_14.0.zip

提取固件

使用 payload-dumper-go 提取所需的固件

payload-dumper-go -o . miui_MUNCH_OS1.0.2.0.ULMCNXM_6438305cc0_14.0.zip

可以提取出许多 img 文件， 下一步用到。

Fastboot 模式刷固件

将手机关机， 然后按住 音量减 + 电源 按钮开机， 进入 Fastboot 模式， 然后使用下面的命令刷入固件：

fastboot flash abl_ab abl.img
fastboot flash aop_ab aop.img
fastboot flash bluetooth_ab bluetooth.img
fastboot flash cmnlib_ab cmnlib.img
fastboot flash cmnlib64_ab cmnlib64.img
fastboot flash devcfg_ab devcfg.img
fastboot flash dsp_ab dsp.img
fastboot flash featenabler_ab featenabler.img
fastboot flash hyp_ab hyp.img
fastboot flash imagefv_ab imagefv.img
fastboot flash keymaster_ab keymaster.img
fastboot flash modem_ab modem.img
fastboot flash qupfw_ab qupfw.img
fastboot flash tz_ab tz.img
fastboot flash uefisecapp_ab uefisecapp.img
fastboot flash xbl_ab xbl.img
fastboot flash xbl_config_ab xbl_config.img

如果一切正常， 重启手机即可。

下载 LineageOS

经过前面的解锁和固件更新，终于可以开始安装 LineageOS 了。 从 LineageOS 的网站下载最新的 K40S 的安装镜像 ， 目前的版本是 lineage-22.2-20251117-nightly-munch-signed.zip ， 文件需要的文件列表为：

• lineage-22.2-20251117-nightly-munch-signed.zip
• boot.img
• dtbo.img
• super_empty.img
• vbmeta.img
• vendor_boot.img

刷写启动 (boot) 分区 和 恢复 (recovery) 分区

再次将手机重启到 Fastboot 模式， 用下面的命令来刷写启动分区：

fastboot flash boot boot.img

刷写启动分区之后， 可以保证恢复 (Recovery) 分区正常工作， 接下来刷写恢复分区：

fastboot flash vendor_boot vendor_boot.img

在恢复模式下清空数据

刷写恢复分区完成之后， 启动到恢复模式：

fastboot reboot recovery

在恢复模式下， 选择 Factory Reset ，然后 Format data / factory reset 清空全部数据 。

重要数据一定要记得提前备份！！！

刷入 LineageOS 系统镜像

在恢复模式下， 选择 Apply Update -> Apply from ADB ， 然后在电脑上执行下面的命令刷入 LineageOS 系统镜像：

adb -d sideload lineage-22.2-20251117-nightly-munch-signed.zip

通常情况下，adb 会报告 Total xfer: 1.00x ，但在某些情况下，即使进程成功，输出可能会停在 47%并显示 adb: failed to read command: Success 。在其他情况下，它可能会显示 adb: failed to read command: No error 或 adb: failed to read command: Undefined error: 0 ，这也是可以的。

刷完 LineageOS 系统镜像之后， 先不要重启手机， 接下来再刷入谷歌服务， 如果不需要谷歌服务的话， 则不需要这一步。

安装谷歌服务

从 MindTheGapps 下载谷歌服务安装包， 目前的版本是 MindTheGapps-15.0.0-arm64-20250812_214357.zip ， 用 adb sideload 命令刷入：

adb -d sideload MindTheGapps-15.0.0-arm64-20250812_214357.zip

手机会提示签名不正确， 这是正常的， 因为 MindTheGapps 没有使用 LineageOS 的签名。

现在可以重启手机， 启动全新的 LineageOS 系统了。

与原版 HyperOS 的对比

感觉比较舒服的几点

• LineageOS 非常简洁， 完全无广告， 这一点足可以把 HyperOS 以及国内一众魔改安卓系统钉死在耻辱柱上；
• LineageOS 体积很小， 大概只有 HyperOS 的 1/3 到一半， 运行起来也非常的轻快， 感觉很流畅；

  不排除是 LineageOS 动画时间短的原因；

• 可以 随意 安装 apk 文件， 不用担心弹出密码认证甚至短信/刷脸认证；
• 肯定不用担心计划性报废， 因为 LineageOS 是开源的， 越升级越流畅， 至少 LineageOS 系统本身是这样的；
• 没有 HyperOS 那些令人厌恶的后台服务， 包括但不限于 快应用 、手机管家 等无法关闭的后台服务；
• 显示刷新率有 3 档， 分别是 60Hz、90Hz、120Hz ， 比 HyperOS 多了 90Hz 一档， 而且还可以选择 流畅画面 (自动将某些内容的刷新频率提高到 120Hz ， 主要是动画和过渡)；
• 谷歌输入法 Gboard 终于适配底部的导航栏了， 比在原生系统上舒服很多， 原生 HyperOS 简直就是故意恶心谷歌输入法；
• 从 Play 市场下载的软件 (包括微信、QQ、 淘宝、 京东、 高德地图等) 在存储卡上乱拉屎的情况都已经没有了， 在应用属性页的电量管理中禁止后台之后也基本不会作妖了， 反观从 HyperOS 市场下载的软件， 简直都是垃圾；
• 可以在 设置 -> 电池 页面为安装的每个应用设置温控策略， 而不必安装什么游戏助手之类的额外软件；

感觉比较遗憾的几点

• 工作日闹钟： LineageOS 是类原生系统， 没有国内系统定制的工作日闹钟是最遗憾的一个功能， 而且好像还找不到替代品；
• NFC门禁卡： HyperOS 有小米钱包， 可以复制小区的门禁卡， 这个在 LineageOS 上暂时没有找到替代品， 这手机的 NFC 我就不知道还有啥用了；
• 天气预报： HyperOS 的天气预报功能还是很贴心的， 不过装了谷歌的服务之后， 也有基于位置的天气预报，虽然没有那么及时， 但是凑合也能用；

意外惊喜

最后还有一个意外的惊喜， 那就是支持游戏手柄震动； 原来的 HyperOS 是基于 Android 14 的， 不支持手柄震动。 安装 LineageOS 之后，系统也升级到了 Android 15 ， 在使用手柄时突然发现可以震动了， 游戏手感可以说是上升了一个档次， 算是最意外的惊喜吧。

if io_bound:
    if io_very_slow:
        print("Use Asyncio")
    else:
        print("Use Threads")
else:
    print("Multi Processing")

介绍

并发是编程中的一个基本概念，它允许应用程序同时执行多个任务。Python 提供了多种用于管理并发的工具：多线程、多进程和异步编程（Python 中的 asyncio 模块）。每个都有独特的优势，适合不同类型的任务。本文深入探讨了这些并发模型，提供了清晰的示例和详细说明，以帮助您了解何时以及如何有效地使用它们。

进程与线程

进程

进程是正在执行的程序的独立实例。每个进程都在自己的内存空间中运行，其自己的资源由作系统分配。进程不与其他进程共享内存，除非明确设计为通过进程间通信 （IPC） 共享内存。

线程

线程是进程中的最小执行单位。同一进程中的多个线程共享相同的内存空间，使它们能够比单独的进程更高效地进行通信。但是，此共享内存可能会导致同步问题。

示例：在 Python 中创建线程

import threading
import time


def print_numbers():
    # This function will run in a separate thread
    for i in range(5):
        print(f"Thread: {i}")
        time.sleep(1)  # Simulate some work with sleep


# Create a new thread object to run print_numbers()
thread = threading.Thread(target=print_numbers)
# Start the thread
thread.start()
# Wait for the thread to finish before exiting the main program
thread.join()
print("Main thread: Execution finished")

解释：

• threading.Thread(target=print_numbers): 创建将运行 print_numbers() 函数的线程；
• thread.start()：开始执行线程。
• thread.join（）：确保主线程等待新线程完成，然后再继续。

多线程与多进程

多线程

多线程允许多个线程在同一进程中并发运行。在 Python 中，多线程中的真正并行性受到全局解释器锁 （GIL） 的限制，该锁一次只允许一个线程执行 Python 字节码。但是，多线程处理对于 I/O 密集型任务仍然很有用，其中线程可以等待外部资源（如文件 I/O 或网络作），而其他线程可以继续执行。

示例：Python 中的多线程

import threading
import time


def worker(name):
    print(f"Worker {name} starting")
    time.sleep(2)  # Simulating I/O-bound work
    print(f"Worker {name} finished")


threads = []


for i in range(5):
    t = threading.Thread(target=worker, args=(i,))
    threads.append(t)
    t.start()

for t in threads:
    t.join()  # Wait for all threads to complete

解释：

• 每个线程通过休眠 2 秒来模拟一些 I/O 绑定工作。
• thread.join() 确保主线程等待所有工作线程完成。

多进程

多进程涉及运行多个进程，每个进程都有自己的 Python 解释器和内存空间。这允许真正的并行性，使多进程成为 CPU 密集型任务的理想选择。

示例：Python 中的多进程

import multiprocessing
import time


def worker(name):
    print(f"Worker {name} starting")
    time.sleep(2)  # Simulate some work
    print(f"Worker {name} finished")


if __name__ == '__main__':
    processes = []

    for i in range(5):
        p = multiprocessing.Process(target=worker, args=(i,))
        processes.append(p)
        p.start()

    for p in processes:
        p.join()  # Wait for all processes to finish

解释：

• 每个工作进程独立运行，从而实现跨 CPU 内核的真正并行性。
• 多进程避免了 GIL，使其适合 CPU 密集型任务。

Asyncio

Asyncio 是一个 Python 库，用于使用 async/await 语法编写并发代码。它专为 I/O 密集型任务而设计，并使用事件循环来管理和计划任务。

Asyncio 中的关键概念

1. 协程 (Coroutines): 使用 async def 定义的函数。这些是 asyncio 的构建块，表示可以暂停和恢复的任务;
2. 事件循环 (Event Loop) ：asyncio 的核心，用于管理任务的执行;
3. Tasks：围绕在事件循环上调度的协程的包装器。
4. await：暂停协程的执行，将控制权交还给事件循环。

示例：Asyncio 基础

import asyncio


async def task(name):
    print(f"Task {name} starting")
    await asyncio.sleep(2)  # Simulate an I/O-bound operation
    print(f"Task {name} finished")


async def main():
    await asyncio.gather(task("A"), task("B"), task("C"))


asyncio.run(main())

解释：

• await asyncio.sleep(2): 暂停协程，允许事件循环运行其他任务;
• asyncio.gather(): 并发运行多个协程。

在 Asyncio 中处理 CPU 密集型的任务

Asyncio 不太适合 CPU 密集型任务，因为它们会阻塞事件循环。但是，您可以使用 asyncio.to_thread() 或 asyncio.run_in_executor() 将 CPU 密集型任务卸载到单独的线程或进程。

示例：卸载 CPU 密集型任务

import asyncio
import time


def cpu_bound_task(n):
    time.sleep(n)  # Simulating a CPU-bound task
    return n * n


async def main():
    result = await asyncio.to_thread(cpu_bound_task, 2)
    print(f"Result: {result}")


asyncio.run(main())

解释：

• asyncio.to_thread(): 将 CPU 绑定的任务卸载到单独的线程，从而允许事件循环保持响应。

常见的误解和错误

混合同步和异步代码

不是需要所有内容都是异步的。可以使用 asyncio.to_thread() 或类似方法在异步代码中调用同步函数。

示例：

import asyncio
import time


def sync_task():
    time.sleep(2)
    return "Completed"


async def main():
    result = await asyncio.to_thread(sync_task)
    print(result)


asyncio.run(main())

直接等待 CPU 密集型任务

直接等待 CPU 绑定的任务可能会阻止事件循环，始终将此类任务卸载到单独的线程或进程。

create_task() 与 await

• await coroutine: 运行协程并等待其完成；
• asyncio.create_task(coroutine)： 安排协程与其他任务并发运行并立即返回。然后，您可以稍后等待该任务。

示例：

import asyncio


async def my_coroutine():
    await asyncio.sleep(2)
    return "Done"


async def main():
    task = asyncio.create_task(my_coroutine())
    print("Doing something else while waiting...")
    result = await task
    print(f"Task result: {result}")


asyncio.run(main())

解释：

• asyncio.create_task()：当您想要启动协程并同时执行其他工作时，此功能非常有用。

何时使用哪种方法

1. 多线程：
   • 最适合 I/O 密集型任务，如网络作或文件 I/O；
   • 当您需要在线程之间共享状态时使用；
   • 由于 Python 中的 GIL，因此不适合 CPU 密集型任务。
2. 多进程：
   • 非常适合需要真正并行性的 CPU 密集型任务；
   • 当您需要绕过 GIL 时使用；
   • 最适合繁重的计算工作负载。
3. asyncio:
   • 非常适合具有许多并发作的 I/O 密集型任务。
   • 非常适合构建高性能网络服务器或具有大量 I/O 密集型任务的应用程序。
   • 不适合没有卸载的 CPU 密集型任务。

示例：FastAPI 中的异步编程

FastAPI 是一个现代 Web 框架，它利用 asyncio 来有效地处理并发请求。它使用 async/await 语法来管理 I/O 绑定作，而不会阻塞服务器。

为什么 FastAPI 使用 Async

1. 可扩展性 ：异步代码允许 FastAPI 以最小的开销处理许多并发连接;
2. 性能 ：对于 I/O 密集型任务，异步可以胜过传统线程;
3. 简单性：与线程代码相比，异步代码通常更易于编写和推理。

在 FastAPI 中卸载 CPU 密集型任务

FastAPI 可以通过将 CPU 密集型任务卸载到线程或进程池来处理这些任务。

from fastapi import FastAPI
from concurrent.futures import ProcessPoolExecutor
import asyncio


app = FastAPI()
process_pool = ProcessPoolExecutor()


def cpu_bound_task(n):
    # Simulate a CPU-bound task
    total = 0
    for i in range(n):
        total += i * i
    return total


@app.get("/compute/{n}")
async def compute(n: int):
    # Offload the CPU-bound task to a separate process
    loop = asyncio.get_running_loop()
    result = await loop.run_in_executor(process_pool, cpu_bound_task, n)
    return {"result": result}

解释：

• ProcessPoolExecutor: 创建一个 ProcessPoolExecutor 来将 CPU 绑定的任务卸载到单独的进程，这确保了主 FastAPI 事件循环保持响应，它的实现由 Uvicorn 内部处理;
• loop.run_in_executor(): 此方法将 cpu_bound_task 卸载给 executor（在本例中为 ProcessPoolExecutor），允许 FastAPI 服务器在并行处理 CPU 密集型任务的同时处理其他请求;
• await: 通过使用 await 确保 FastAPI 处理程序在返回结果之前等待 CPU 绑定的任务完成。

为什么卸载很重要

在 Web 应用程序中，响应能力是关键。如果你直接在 FastAPI 事件循环中运行 CPU 密集型任务，它会阻止服务器处理其他请求，直到任务完成。通过卸载到单独的进程或线程，服务器可以继续并发处理传入请求，从而获得更好的可扩展性和用户体验。

结论

Python 中的并发是一个强大的工具，允许您编写高效且可扩展的应用程序。无论您是处理 I/O 密集型任务、CPU 密集型计算，还是两者兼而有之，Python 都提供了各种并发模型（多线程、多进程和 asyncio）来满足您的需求:

• 多线程： 最适合共享内存有用的 I/O 密集型任务，但由于 GIL 的原因，它不适合 CPU 密集型任务;
• 多进程：非常适合需要真正并行性的 CPU 密集型任务，避免了 GIL 的限制;
• Asyncio：非常适合涉及大量并发作的 I/O 绑定任务，提供非阻塞并发。

参考资料：

• Concurrency in Python: Understanding Threading, Multiprocessing, and Asyncio
• stackoverflow

不过最近新发布的 ANEMLL 项目， 号称可以在苹果 NPU 上运行大模型， 觉得非常好奇， 决定体验并记录下来。

ANEMLL 项目介绍

ANEMLL 的目标是在苹果 NPU 上运行现有的 HuggingFace 上的大模型， 目前最新版本是 0.1.2-alpha ， 暂时只支持 llama 架构的模型， 比如 LLAMA 架构的模型，Meta LLaMA 3.1 以及 DeepSeek 蒸馏过的 Llama 3.1 模型， 未来会增加更多架构的模型。

对 ANEMLL 项目感兴趣的话， 可以在 github 上为作者加个 🌟 支持一下。

接下来就按照 ANEMLL 项目的说明， 尝试将 Llama-3.2-1B-Instruct 模型转换成 CoreML 格式， 在 NPU 上运行，然后再和 GPU 运行做个对比， 看看有什么优势。

环境准备

将模型转换成 CoreML 格式， 必须安装的软件：

• XCode 命令行的苹果开发者工具是不够的， 可以从 AppStore 下载；
• Python 3.9 刚好是 XCode 内置的 Python 版本， 估计是 XCode 兼容性比较好， 所以才会推荐使用这个版本 （实际测试， 从 HomeBrew 下载的 3.12 版本的 Python 也可以运行）。

至于 Git 和 Git-LFS 则不是必须的， 因为下载模型也不一定用 git 嘛。

转换模型格式

转换模型包括3部分： 嵌入 (Embeding) ， 前馈网络/层 (Feed Forward Network/layers) 和 LM 头 (LM Head) ， 要了解详情， 可以查看官方文档 ANE_converter 。

ANEMLL 提供了转换脚本 convert_model.sh 将 LLM 模型转换为 CoreML 模型， 用法如下：

./anemll/utils/convert_model.sh \
    --model ../Meta-Llama-3.2-1B \
    --output ./converted_models

然后就是等了， 大概需要5分钟左右的时间。

如果不想折腾， 也可以从 https://huggingface.co/anemll 下载作者转换好的模型来运行。

使用 NPU 运行转换后的模型

使用 chat_full.py 来和模型对话， 命令如下：

python3 chat_full.py --meta llama-3.2-1b-instruct/meta.yaml

聊天截图如下

运行 llama-3.2-1b-instruct 模型， 输出速度是 35 t/s ， 不算快， 大概是 M1 Max 用 mlx 引擎运行 llama-3.2-1b-instruct 模型的 1/3 。

NPU 使用率如下图所示：

首先， NPU 功耗确实很低， 只有 2.8W ，如果是用 mlx 来运行大模型， 显卡功耗差不多有 30W 了， 功耗只需要显卡的 1/10 。

有一点比较奇怪， NPU 使用率只有 30% 左右， 于是在 X 上问作者是什么原因， 作者回复说主要是因为 NPU 带宽不够， 在等数据加载， 也就是说带宽限制了 NPU 的发挥。

估计这也是为什么苹果发布会只说带了多少核心的 NPU ， 其它参数却只字不提的原因吧。

总结

总的来说， 以 NPU 运行大模型还是不错的， 相比显卡运行来说， 1/10 的功耗， 1/3 速度， 对于移动设备，笔记本来说还是非常友好的。

如果这个项目以后能够让 NPU 全速运行速度， 速度提高3倍和 GPU 差不多了， 就算功耗也增加3倍， 相比 GPU 还是有很大的优势。

真心希望未来能够在 NPU 上运行各种模型， 就像现在在显卡上运行一样。

- src
- src/layers/particle-layer.ts
- src/layers/particle-layer.fragment.glsl
- src/layers/particle-layer.vertex.glsl

原来用 esbuild 进行转译和打包， 配置起来非常的容易， 直接使用内置的 loader 就可以处理， esbuild 的配置如下：

export default {
  entryPoints: './src/main.ts',
  outdir: './dist',
  splitting: true,
  chunkNames: 'chunks/[name]-[hash]',
  tsconfig: './tsconfig.json',
  loader: {
    '.glsl': 'text'
  }
}

上面的配置就是告诉 esbuild 将 glsl 作为文本来加载， 在 ts 或 js 文件中可以直接 import 导入使用，代码如下：

import vertex from './particle-layer.vertex.glsl'
import fragment from './particle-layer.fragment.glsl'

现在切换到 Vite 做转译和打包工具， 发现没有类似 esbuild 这样指定文件类型的处理方式。 虽然 Vite 有调用 esbuild ， 其配置文件也支持 esbuild 选项， 但是只是 esbuild 的 transform 选项， 不是完整的 build 选项， 因此不能像 esbuild 那样简单指定 loader 来解决。

查看了 Vite 配置文件的 resolve 选项， 发现更多是关于路径方面的配置， 而不是文件内容相关的配置， 也无法解决这个问题。

也尝试了 Vite 配置文件的 optimizeDeps.esbuildOptions ， 虽然是完整的 esbuild 选项， 能够指定 loader ， 运行时会出错。

export default {
  base: '',
  publicDir: 'public',
  server: {
    host: '127.0.0.1',
    port: 3000,
  },
  optimizeDeps: {
    esbuildOptions: {
      loader: {
        '.glsl': 'text'
      }
    }
  },
}

运行时错误信息如下：

vite v6.0.7 building for production...
✓ 38 modules transformed.
x Build failed in 530ms
error during build:
src/layers/particle-layer/particle-layer-vertex.glsl (1:8): Expected ';', '}' or <eof> (Note that you need plugins to import files that are not JavaScript)
file: ~/Developer/javascript//wind-demo/src/layers/particle-layer/particle-layer-vertex.glsl:1:8

1: #define SHADER_NAME particle-layer-vertex-shader
           ^
2: #ifdef GL_ES
3: precision highp float;

这看起来应该是直接把 glsl 文件的内容当作 js 了。

那看起来应该是不能通过配置来实现 esbuild 原来的功能， 只能写一个插件来解决吧， 好在插件比较简单， 很容易实现， 代码如下：

function glslPlugin() {
  return {
    name: 'glsl-plugin',
    transform(code, id) {
      if (id.endsWith('.glsl')) {
        return {
          code: 'export default `' + code + '`;',
          map: null,
        };
      }
    },
  };
}

当然， 插件也可以写的更加复杂一些， 比如去除 glsl 文件中的空格/注视，甚至混淆等， 不过这些都可以后期再处理， 先能用再说。

最终的 Vite 配置文件如下：

export default defineConfig({
  base: '',
  publicDir: 'public',
  server: {
    host: '127.0.0.1',
    port: 3000,
  },
  plugins: [
    glslPlugin()
  ],
  build: {
    target: 'esnext',
  }
});

在 GDAL 的文档中， 已经详细介绍了 C/C++ 语言增加的 函数和使用方法 ，本文就不再介绍。 接下来主要介绍一下如何 C# 和 Python 两种语言中如何使用这一功能。

在 C# 中线程安全的读取栅格数据

GDAL 在 C# 语言绑定中， 为栅格数据集 Dataset 增加了 IsThreadSafe 和 GetThreadSafeDataset 两个成员函数， 定义如下：

public class Dataset : MajorObject {
  
  public Dataset GetThreadSafeDataset(int nScopeFlags) {}

  public bool IsThreadSafe(int nScopeFlags) {}

}

这样我们就可以判断一个栅格数据集是否是线程安全的，如果不是，则再打开一个线程安全的数据集，代码如下：

// 从第三方类库获取一个已经打开的数据集
var dataset = GetDatasetFromOtherLibs();
// 判断是不是线程安全的
var isThreadSafe = dataset.IsThreadSafe(GDAL_OF_RASTER);
// 如果不是，再打开一个线程安全的栅格数据集
if (!isThreadSafe) {
  dataset = dataset.GetThreadSafeDataset(GDAL_OF_RASTER);
}

当然， 如果能够自行打开栅格数据， 则推荐使用 Gdal.OpenEx 方法直接打开线程安全的数据集：

public static class GdalExtensions {
  // GDAL 并没有为在 C# 绑定中定义这些常量， 自己定义一下需要的常量
  const int GDAL_OF_READONLY = 0x00;
  const int GDAL_OF_RASTER = 0x02;
  const int GDAL_OF_THREAD_SAFE = 0x800;

  public static Dataset OpenThreadSafeDataset(string tiffFile) {
    // reffer [GDALOpenEx](https://gdal.org/en/latest/api/raster_c_api.html#gdal_8h_1a9cb8585d0b3c16726b08e25bcc94274a)
    var threadSafeDataset = Gdal.OpenEx(
      tiffFile,
      (uint)(GDAL_OF_RASTER | GDAL_OF_READONLY | GDAL_OF_THREAD_SAFE),
      null,
      null,
      null
    );
    return threadSafeDataset;
  }
}

1. GDAL_OF_XXX 常量的值在 gdal.h 文件中可以找到；
2. OpenEx 函数个参数的意义参考 C 语言函数 GDALOpenEx ；

可以通过上面定义的扩展函数直接打开一个线程安全的只读栅格数据集：

var dataset = GdalExtensions.OpenThreadSafeDataset("mydata.tif");

这样获取到线程安全的 dataset 之后，可以轻松实现一个栅格数据切片服务，示例代码如下：

using MaxRev.Gdal.Core;
using OSGeo.GDAL;
using SkiaSharp;

GdalBase.ConfigureAll();
Gdal.UseExceptions();

// 墨卡托坐标系的 GeoTiff 文件
var tiffFile = "mydata.tif";

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("api/tile/{z:int}/{y:int}/{x:int}", (int z, int x, int y) => {
    Dataset? dataset = null;
    try {
        var tile = new Tile(x, y, z);
        dataset = GdalExtensions.OpenThreadSafeDataset(tiffFile);
        // 参照 https://cogeotiff.github.io/rio-tiler/ 实现了一个 ReadTile 函数，
        // 从 GeoTiff 文件读取按墨卡托坐标系下的地图切片对应的图片
        var image = dataset.ReadTile(tile);
        if (image == null)  {
            return Results.NotFound();
        }
        var buffer = image.Encode(
            SKEncodedImageFormat.Png, 90
        ).ToArray();
        return Results.File(buffer, "image/png");
    }
    catch (Exception ex) {
        Console.WriteLine(ex);
        throw;
    }
    finally {
        dataset?.Dispose();
    }
}).WithName("GetTile");

app.Run();

在 Python 中线程安全的读取栅格数据

Python 和 C# 都是 GDAL 官方支持的，因此用法也基本上是一样的。

判断一个栅格数据集是否是线程安全的，如果不是，则再获取一个新的线程安全的数据集：

from osgeo import gdal

gdal.UseExceptions()

dataset: gdal.Dataset = open_dataset_from_other_lib()

is_thread_safe = dataset.IsThreadSafe(gdal.OF_RASTER)
print(f'is thread safe: {is_thread_safe}')

if not is_thread_safe:
    safe_dataset: gdal.Dataset = dataset.GetThreadSafeDataset(gdal.OF_RASTER)
    is_thread_safe = safe_dataset.IsThreadSafe(gdal.OF_RASTER)
    print(f'is thread safe: {is_thread_safe}')
    safe_dataset.Release()

dataset.Release()

也可以通过 gdal.OpenEx 直接打开线程安全的栅格数据集：

from osgeo import gdal

gdal.UseExceptions()

dataset: gdal.Dataset = gdal.OpenEx(
    'mydata.tif',
    gdal.OF_READONLY | gdal.OF_RASTER | gdal.OF_THREAD_SAFE
)

is_thread_safe = dataset.IsThreadSafe(gdal.OF_RASTER)

print(f'is thread safe: {is_thread_safe}') # True

dataset.Release()

GDAL 的 Python 绑定定义的常量比 C# 多一些， 但是类型提示则大多都是 Any 。

定义数据库方言 (Dialect)

NHibernate 对不同提供了相应的数据库方言 (Dialect) ，要添加数组类型支持，自然要从数据库方言(Dialect)开始：

public class NpgSqlDialect : NHibernate.Dialect.PostgreSQLDialect {
  
  public NpgSqlDialect() {}

}

在 NHibernate 配置文件中添加下面的配置使用这个方言：

<property name="dialect">NHibernate.Extensions.NpgSql.NpgSqlDialect,NHibernate.Extensions.NpgSql</property>

定义用户数据类型 (UserType)

在 NHibernate 中扩展自定义数据类型， 需要实现 NHibernate.UserTypes.IUserType 接口, 因此需要定义一个 ArrayType 并实现 IUserType 接口， 部分代码如下:

public class ArrayType<T> : IUserType {

  public SqlType[] SqlTypes => [GetNpgSqlType()];

  public System.Type ReturnedType => typeof(T[]);
  
  public bool IsMutable => false;
  
  public object Assemble(object cached, object owner) { }
  
  public object Disassemble(object value) { }
  
  public object? DeepCopy(object value) { }
  
  public new bool Equals(object? x, object? y) { }
  
  public int GetHashCode(object? x) { }
  
  public object? NullSafeGet(DbDataReader rs, string[] names, ISessionImplementor session, object owner) { }
  
  public object Replace(object original, object target, object owner) { }
  
}

为了减少冗余的代码， 将 ArrayType 定义成范型类型。 如果想了解全部实现代码，请查看 ArrayType.cs 的源代码。

接下来在上面定义的 NpgSqlDialect 中，注册常用的数组类型（以 int[] 和 string[] 为例）：

public class NpgSqlDialect : NHibernate.Dialect.PostgreSQLDialect {
  
  public NpgSqlDialect() {
    RegisterUserTypes();
  }
  
  private void RegisterUserTypes() {
    TypeFactory.RegisterType(
      typeof(int[]),
      NHibernateUtil.Custom(typeof(ArrayType<int>)),
      ["int[]"]
    );
    TypeFactory.RegisterType(
      typeof(string[]),
      NHibernateUtil.Custom(typeof(ArrayType<string>)),
      ["string[]"]
    );
  }

}

现在，就可以在配置和sql查询中使用数组类型了，在实体映射中这样使用：

[Class(Schema = "public", Table = "arr_test")]
public class ArrTestEntity {
    [Id(Name = nameof(Id), Column = "id", Type = "long", Generator = "trigger-identity")]
    public virtual long Id { get; set; }
    [Property(Column = "int_arr", Type = "int[]")]
    public virtual int[] IntArr { get; set; }
    [Property(Column = "str_arr", Type = "string[]")]
    public virtual string[] StrArr { get; set; }
}

或者使用 xml 映射：

<class table="arr_test" schema="public" name="UnitTest.ArrTestEntity,UnitTest">
  <id name="Id" type="long" column="id" generator="trigger-identity" />
  <property name="IntArr" type="int[]" column="int_arr" />
  <property name="StrArr" type="string[]" column="str_arr" />
</class>

使用 SQL 进行查询过滤：

string[] strArr = ["a", "c"];
var sqlQuery = session.CreateSQLQuery(
  $"select * from public.arr_test where strArr = any(:{nameof(strArr)})"
);
sqlQuery.SetParameter(
  nameof(strArr),
  strArr,
  NHibernateUtil.Custom(typeof(ArrayType<string>))
);
var data = sqlQuery.List<ArrTestEntity>();
Assert.That(data, Is.Not.Empty);

当然，仅支持属性类型映射和 SQL 查询过滤是不够的， 因为最常用的是 Linq 查询， 接下来继续让 Linq 查询也支持数组类型过滤。

定义 HQL 数组过滤函数

数组条件过滤函数最常用的有两个：

1. 数组是否包含某一个元素，SQL 查询表达式为： element = ANY(array) ;
2. 两个数组是否有共同的元素， SQL 查询表达式为： array1 && array2 ；

NHibernate Linq 是基于 HQL 的， 因此需要先让 HQL 能够支持数组过滤， HQL 支持比较容易实现， 只需要在上面定义的 NpgSqlDialect 中添加对应的 SQL 函数模板：

public class NpgSqlDialect : NHibernate.Dialect.PostgreSQLDialect {
  
  public NpgSqlDialect() {
    RegisterFunctions()
  }
  
  private void RegisterFunctions() {
    // array_contains(arr, 3) => :num = any(arr)
    RegisterFunction(
      "array_contains",
      new SQLFunctionTemplate(NHibernateUtil.Boolean, "?2 = any(?1)")
    );
    // array_intersects => ?1 && ?2
    RegisterFunction(
      "array_intersects",
      new SQLFunctionTemplate(NHibernateUtil.Boolean, "?1 && ?2")
    );
  }

}

注册了 SQL 函数模板之后，就可以在 HQL 查询中使用数组类型进行过滤：

string[] strArr = ["a", "c"];
var query1 = session.CreateQuery(
  $"from ArrTestEntity e where array_intersects(e.StrArr, :{nameof(strArr)})"
);
query1.SetParameter(nameof(strArr), strArr, NHibernateUtil.Custom(typeof(StringArrayType)));
var data1 = query1.List<ArrTestEntity>();
Assert.That(data1, Is.Not.Empty);

对应生成的的 SQL 语句为：

select
  arrtestent0_.id as id1_2_,
  arrtestent0_.int_arr as int2_2_,
  arrtestent0_.str_arr as str3_2_ 
from
  public.arr_test arrtestent0_ 
where
  arrtestent0_.str_arr && :p0;

定义 Linq 扩展查询

终于来到了最关键的一步，有点儿复杂， 但是也不难。 先定义两个针对数据类型的扩展函数， 分别对应上面定义的 array_contains 和 array_intersects HQL 扩展函数，代码如下：

public static class ArrayExtensions {

  public static bool ArrayContains<T>(this T[] array, T element) {
    return array.Contains(element);
  }

  public static bool ArrayIntersects<T>(this T[] array, T[] other) {
    return array.Intersect(other).Any();
  }

}

这里只需要函数定义即可，与如何实现没有关系，因为会被转换成对应的 HQL 查询， 不会真正执行这两个表达式。

定义数据类型生成器 (Generator)，也就是将 Linq 表达式转换成对应的 HQL 表达式：

public class ArrayHqlGenerator : BaseHqlGeneratorForMethod {

  public ArrayHqlGenerator() {
    SupportedMethods = [
      ReflectHelper.GetMethodDefinition<int[]>(
        x => x.ArrayContains(0)
      ),
      ReflectHelper.GetMethodDefinition<int[]>(
        x => x.ArrayIntersects(Array.Empty<int>())
      ),
    ];
  }

  public override HqlTreeNode BuildHql(
    MethodInfo method,
    Expression targetObject,
    ReadOnlyCollection<Expression> arguments,
    HqlTreeBuilder treeBuilder,
    IHqlExpressionVisitor visitor
  ) {
    var hqlMethod = "";
    var linqMethod = method.Name;

    hqlMethod = linqMethod switch {
      "ArrayContains" => "array_contains",
      "ArrayIntersects" => "array_intersects",
      _ => hqlMethod
    };
    if (string.IsNullOrEmpty(hqlMethod)) {
      throw new HibernateException($"Method {method.Name} not found");
    }
    return treeBuilder.BooleanMethodCall(
      hqlMethod,
      arguments.Select(visitor.Visit).Cast<HqlExpression>()
    );
  }

}

最后，定一个 LinqToHqlGeneratorsRegistry 将上面定义的 ArrayHqlGenerator 合并进默认的 DefaultLinqToHqlGeneratorsRegistry ， 代码如下：

public class LinqToHqlGeneratorsRegistry : DefaultLinqToHqlGeneratorsRegistry {

    public LinqToHqlGeneratorsRegistry() {
        this.Merge(new ArrayHqlGenerator());
    }

}

修改 nhibernate.config 配置文件， 使用新定义的 LinqToHqlGeneratorsRegistry ：

<property name="linqtohql.generatorsregistry">NHibernate.Extensions.NpgSql.LinqToHqlGeneratorsRegistry,NHibernate.Extensions.NpgSql</property>

就可以在 Linq 查询中使用数组过滤表达式了:

string[] strArr = ["a", "c"];
var query1 = session.Query<ArrTestEntity>().Where(
    x => x.StrArr.ArrayIntersects(strArr)
);
var data1 = await query1.ToListAsync();
Assert.That(data1, Is.Not.Empty);

int[] intArr = [1, 3];
var query2 = session.Query<ArrTestEntity>().Where(
    x => x.IntArr.ArrayIntersects(intArr)
);
var data2 = await query2.ToListAsync();
Assert.That(data2, Is.Not.Empty);

var query3 = session.Query<ArrTestEntity>().Where(
    x => x.StrArr.ArrayIntersects(strArr) && x.IntArr.ArrayIntersects(intArr)
);
var data3 = await query3.ToListAsync();
Assert.That(data3, Is.Not.Empty);

而且， 还可以反向使用 ArrayContains ：

var idArr = idList.ToArray();
var query2 = session.Query<ArrTestEntity>().Where(
    x => idArr.ArrayContains(x.Id)
);
var data2 = query2.ToList();
Assert.That(data2, Is.Not.Empty);

最后要特别感谢 NHibernate 核心成员 @fredericDelaporte 和 hazzik ，在实现的过程中提供了不少帮助。

与其它类似的 AI 智能代码提示工具不同， Continue 是开源的， 支持调用本地部署的大模型服务， 可以在企业内部甚至是安全隔离的局域网中运行， 并且提供了完善本地运行的文档。如果是私有代码库， 无法使用基于互联网的 AI 智能提示， 那么使用 Continue 搭建本地的智能代码提示， 也能达到比较好的效果 （当然不能与收费的 GitHub Copilot 媲美）。

Continue 介绍

以下功能介绍搬运自 Contine 的官方代码库。

Continue 是领先的开源代码助手。您可以连接任何模型和任何上下文，以在 VS Code 和 JetBrains 中构建自定义自动完成和聊天体验， 主要功能有：

更容易地理解代码片段 利用 AI 来解释代码段， 理解更容易。

自动完成代码建议 利用 AI 理解代码上下文， 提供智能提示， 按 Tab 键自动补全。

随时重构 利用 AI 随时随地进行重构。

代码库问答 利用 AI 基于你的代码库进行问答。

快速文档上下文 快速使用框架的文档作为问答上下文。

模型选择

Continue 支持的模型非常多，具体可以看 选择模型 这篇文档， 根据这篇文档的建议， 需要运行两个模型实例：

• 问答： 建议使用 30B 以上参数的模型， 文档给的建议是 llama-3 ：
  • 算力充足 llama-3-70B ；
  • 算力有限 llama-3-8B ；
• 代码提示： 建议使用 1～15B 参数即可， 文档给的建议是:
  • DeepSeek Coder：
    • 算力充足 deepseek-coder-v2:16b ；
    • 算力有限 deepseek-coder:6.7b 或者 deepseek-coder:1.3b ；
  • StarCoder 2 ：
    • 算力充足 starcoder-2-7b ；
    • 算力有限 starcoder-2-3b ；

经过实际测试， 建议的本地运行模型为：

• 问答模型， 选择 llama-3-8B 或者同级别的模型就可以了， 一般不会达到运行 llama-3-70B 的硬件；
• 代码提示模型， 如果你有一张不是太旧的独立显卡，比如 12G 显存的 3060 ， 就可以流畅运行 starcoder-2-7b 了， 安装了 cude 之后， 体验非常好； 如果没有， 则可以运行 starcoder-2-3b ， 也能体验到不错的效果；

如果算力有限， 优先运行代码提示模型， 因为这个使用的频率非常高， 在输入代码的同时， 会频繁的调用。 问答模型用的频率比较低， 因为需要用户主动提问。

llama.cpp

建议使用 llama.cpp 来运行大模型， 因为 llama.cpp 提供了非常灵活的选项， 对硬件支持也比较完善。 不管你是 Windows 系统还是 M1 芯片的 Mac 系统， 独立显卡还是集成显卡，甚至是 CPU 是否支持 AVX 指令， 都有特定的预编译版本， 根据自己电脑的硬件信息下载预编译的 llama.cpp 二进制文件即可。

当然也可以根据 llama.cpp 的 说明文档 ， 拉取源代码， 根据自身的硬件信息进行编译， 以获得最佳性能。

关于 llama.cpp 的使用， 可以参考文章 在 Macbook M1 上运行 AI 大模型 LLAMA ， 文中也介绍了如何下载并转换模型文件。

运行代码提示模型

下载 starcoder2-7b 或者 starcoder2-3b 作为代码提示模型， 使用 llama.cpp 的 llama-server 运行， 命令如下：

llama.cpp/llama-server --host 0.0.0.0 --port 28080 \
  --threads 8 --parallel 1 --gpu-layers 999 \
  --ctx-size 8192 --n-predict 1024 --defrag-thold 1 \
  --model models/starcoder2-3b-q5_k_m.gguf

如果只是个人使用的话， 对于代码提示来说， 3b 就足够了。 当然， 如果 GPU 算力充足的话， 也可以运行 7b 或者更高的模型。

经过测试， starcoder 提供的提示效果比 deepseek-coder 要好很多。

运行问答模型

下载 llama-3-8b 作为问答模型， 同样使用 llama.cpp 的 llama-server 运行， 命令如下：

llama.cpp/llama-server --host 0.0.0.0 --port 8080 \
  --threads 8 --parallel 1 --gpu-layers 999 \
  --ctx-size 8192 --n-predict 1024 --defrag-thold 1 \
  --model models/meta-llama-3-8b-instruct.fp16.gguf

Continue 安装与配置

Continue 提供了 Jetbrains IDE 以及 VSCode 的插件， 以 VSCode 为例， 只需要在 VSCode 的扩展窗口中搜索 Continue.continue , 下载并安装即可。

安装之后， 可以直接跳过 Continue 的向导提示， 然后编辑它的配置文件 ~/.continue/config.json ， 直接复制粘贴下面的 json 内容：

{
  "models": [
    {
      "title": "LLaMA",
      "provider": "llama.cpp",
      "model": "llama3-8b",
      "apiBase": "http://127.0.0.1:8080"
    }
  ],
  "tabAutocompleteModel": {
    "title": "LLaMA",
    "provider": "llama.cpp",
    "model": "starcoder2-3b",
    "apiBase": "http://127.0.0.1:28080"
  },
  "allowAnonymousTelemetry": false,
  "embeddingsProvider": {
    "provider": "transformers.js"
  }
}

保存配置文件， Continue 插件会自动根据配置文件自动更新。

starcoder 模型支持10多种常见的开发语言， 因此只要配置好了 Continue 插件， 不管是写前端代码还是后端代码， 都可以享受 AI 带来的智能提示。

如果你的电脑 GPU 算力充足， 还可以把这个配置分享内网的小伙伴， 一起分享 AI 带来的便利。

总结

本地运行的优势就不依赖互联网网络， 几乎没有什么网络延时， 也不需要注册什么账户之类的操作， 没有任何敏感代码泄漏的风险。 主要是显卡的负载， CPU 负载不高， 所以也几乎感觉不到卡顿。

Vite 对于单个前端项目的路由支持的非常好， 不用任何配置，就会自动回落 (Fallback) 到默认页面 /index.html ， 因此对于单个前端项目来说非常的友好。

但是， 如果前端项目中采用了工作区 (monorepo) ， 通常会有多个前端应用，这时 Vite 的支持就没那么好了。 以 pnpm 的工作区为例， 目录结构如下：

- root/
  - apps/
    - app1/
      - index.html
      - ...
    - app2/
      - index.html
      - ...
  - packages/
    - lib1/
    - lib2/
  - package.json
  - pnpm-workspace.yaml
  - vite.config.js

app1 和 app2 分别是两个独立的前端应用，分别有自己的路由， app1/xxx 应该回落到 app1/index.html ， app2/yyy 应该回落到 app2/index.html 。 lib1 和 lib2 分别是两个共享的类库项目。

Vite 支持这种情景下的构建， 根据 Vite 官方文档中的多页面应用模式， 进行如下配置即可：

// vite.config.js
import { resolve } from 'path'
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        app1: resolve(__dirname, 'apps/app1/index.html'),
        app2: resolve(__dirname, 'apps/app2/index.html'),
      },
    },
  },
})

有了上面的配置， 执行 vite build 命令，就可以同时编译两个前端应用。

但是在开发时，Vite 却不能同时处理两个前端应用的路由，即将 app1/xxx 回落到 app1/index.html ， app2/yyy 回落到 app2/index.html 。 而且翻看 Vite 的文档， 也没有找到相关的配置项。

其实这个问题很容易处理， 只要给 vite 内置的开发服务器 (dev server) 添加一个中间件， 修改一下浏览器的请求的路径即可。 不过 Vite 不像 browser-sync 那样， 没有直接给开发服务器配置中间件的选项，只能通过插件 API 对内部的开发服务器进行配置，来添加处理 http 请求的中间件， 那就只能开发一个简单的插件来实现了， 代码如下：

// spafallback-plugin.js
import fs from 'fs';

// 使用正则表达式定义一些 fallback 规则， 将 apps/app1/ 下除了 assets 目录之外
// 的请求都回落到 apps/app1/index.html
const fallbackRules = [
  { pattern: '^/apps/app1/(?!assets/).*', fallback: '/apps/app1/index.html' },
  { pattern: '^/apps/app2/(?!assets/).*', fallback: '/apps/app2/index.html' },
];

/** 定义一个 spaFallback 插件并导出 */
export default function spaFallbackPlugin() {
  // Vite 默认的 public 目录
  let publicDir = 'public';
  // 用正则表达式定义一些不需要处理的路径规则， 包括
  // 其它插件的路径， 源代码路径， node_modules 目录下的文件等，
  // 这些 URL 不需要在这个中间件中进行处理。
  // 如果还有其它的插件， 则下面的表达式可能还需要进行相应的修改。
  const bypassRegex = /@vite|@react-refresh|\/src\/|\/node_modules\/|\.map$/;
  // 定义一个处理请求的中间件， API 形式和 browser-sync 的中间件一致， 
  // vite 使用了相同的库 [connect](https://github.com/senchalabs/connect)
  // 来处理 http 请求。
  function spaFallbackMiddleware(req, res, next) {
    const baseURL =  (req.protocol || 'http') + '://' + req.headers.host + '/';
    const uri = new URL(req.url,baseURL);
    const pathname = uri.pathname;
    // 如果是不需要处理的 URL 的话， 直接调用 next 并返回；
    if (fs.existsSync(__dirname + pathname)
        || fs.existsSync(publicDir + pathname)
        || bypassRegex.test(pathname)
    ) {
      next();
      return;
    }
    // 接下来就是根据上面定义的回落规则进行匹配， 如果请求的 URL 被某一条规则匹配到，
    // 修改当前请求的 URL 为对应的回落地址。
    for (const rule of fallbackRules) {
      const regex = new RegExp(rule.pattern);
      if (regex.test(req.url)) {
        let url = rule.fallback;
        if (uri.search) {
          url += uri.search;
        }
        // 向控制台输出一下修改的路径信息，便于调试
        console.debug(`${pathname} change to: ${url}`);
        req.url = url;
        break;
      }
    }
    next();
  }
  // 返回 vite 插件定义 
  return {
    name: 'spa-fallback',
    enforce: 'pre',
    apply: 'serve',
    configureServer: (server) => {
      // 为 dev server 添加中间件， 这一步非常重要。
      publicDir = server.config.publicDir;
      server.middlewares.use(spaFallbackMiddleware);
    }
  }
}

上面的代码不算很难， 而且注释也很全面，就不再解释了。 接下来就是在 vite.config.js 中使用这个插件， 代码如下：

// vite.config.js
import { resolve } from 'path'
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react';

// 导入上面定义的 spaFallback 插件
import spaFallback from './spafallback-plugin.js';

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        app1: resolve(__dirname, 'apps/app1/index.html'),
        app2: resolve(__dirname, 'apps/app2/index.html'),
      },
    },
  },
  plugins: [
    spaFallback(), //  注意把 spaFallback 插件放在最前面
    react(),
  ]
})

现在 vite serve 应该就可以正确的处理多个前端项目的路由了！

最后，感觉 Vite 是把 esbuild 、 rollup 以及 browser-sync 这三个流行的工具整合到了一起，基本上做到了开箱可用， 确实节省了很多配置的工作，但是有些高级选项 (比如本文用到的 http 中间件配置) ，却不能直接进行配置， 只能通过插件 API 进行配置。

环境准备

在 MacBook 上本地运行大模型， 如要准备 Python 和 Xcode 以及 Git ， 如果还没有安装的话， 按照下面的命令安装即可， 如果已经安装好了， 就可以跳过这两个步骤。

Python

Python 目前建议安装 3.10 版本， 各方面支持都比较完善。

brew install python@3.10

Python 安装好之后， 再安装 torch torchaudio torchvision ， 命令如下：

pip3.10 install torch torchaudio torchvision

Xcode

Xcode 也是必须的， 因为接下来要从源代码编译 llama.cpp。 如果还没有安装 Xcode ， 只要 Xcode 的命令行版本就可以， 在终端中输入下面的命令， 根据提示操作即可。

xcode-select --install

Git

除了基本的 Git 之外， 下载模型文件还需要 Git LFS ， 可以用下面的命令一起安装：

brew install git git-lfs

完成之后， 输入下面的命令初始化 Git LFS :

git lfs install

下载 llama.cpp 源代码并编译

llama.cpp 对 M1 系列的 CPU 进行了专门的优化， 不仅可以充分发挥苹果 M1 芯片统一内存的优势， 而且能够调用 M1 芯片的显卡， 所以在 MacBook 上运行大模型， llama.cpp 是首选。

虽然 llama.cpp 提供编译好的二进制文件下载， 但是很多脚本和示例都在源代码中，因此还是需要克隆源代码下来并编译。

git clone git@github.com:ggerganov/llama.cpp.git

在 macOS 系统上， 只需要进入到 llama.cpp 目录， 然后执行 make 命令即可：

cd llama.cpp
make

llama.cpp 很活跃， 经常更新， 可以通过下面的命令更新并编译：

cd llama.cpp
git pull
make

其它系统可以参照 llama.cpp 的 说明 进行编译。

下载模型

模型就要根据自己电脑的配置有选择的下载， 对于个人电脑来说， 一般是 7b/13b/34b 参数的模型， 再多参数的模型就没必要下载了， 不仅体积庞大，费时费力， 而且在个人电脑上几乎无法运行。

我的 MacBook 的配置是 M1 Max 64G + 1T ， 最多可将 50G 左右的内存做显存使用， 最终保留了下面几个模型文件， 仅供参考。

• CodeLlama-7b-Instruct-hf
• CodeLlama-13b-Instruct-hf
• CodeLlama-13b-Python-hf
• Phind/Phind-CodeLlama-34B-v2
• 01-ai/Yi-34B-200K

以 CodeLlama-7b-Instruct-hf 为例， 下载命令为：

# 确认 git lfs 已经安装
git lfs install

# 在中国大陆从 huggingface 下载模型需要代理
export HTTPS_PROXY=socks5://127.0.0.1:1080
export HTTP_PROXY=socks5://127.0.0.1:1080
export ALL_PROXY=socks5://127.0.0.1:1080

# 下载模型文件
git clone --progress git@hf.co:codellama/CodeLlama-7b-Instruct-hf codellama-7b-instruct-hf

接下来就是等待， 考验代理的稳定性与速度的时刻到了。 如果中途下载失败， 输入下面的命令可以继续， 不需要重新开始：

cd codellama-7b-instruct-hf
git git restore --progress --source=HEAD :/

转换格式以及量化

将模型转换为 llama.cpp 支持的 gguf 格式， 在 llama.cpp 目录下， 执行命令：

python3.10 convert.py models/codellama-7b-instruct-hf

完成之后会在 codellama-7b-instruct-hf 目录下生成对应的 gguf 文件。

量化

我的理解， 量化其实就是对模型就行适当的简化， 这篇文章 Quantize Llama models with GGUF and llama.cpp 说的很清楚， 建议使用 q5_k_m 模式进行量化。

llama.cpp/quantize models/codellama-7b-instruct-hf.f16.gguf models/codellama-7b-instruct-hf.q4_0.gguf q5_k_m

如果机器配置够高的话， 也可以不做量化，直接运行。 在 M1 Max 64G 内存的配置上， 可以直接运行 7b 参数级别的模型， 更多参数的模型则需要量化之后才能运行。

运行模型

命令行

在默认情况下， 将会调用模型输出一段文字，然后退出。

llama.cpp/main -m ./models/chinese-llama-2-13b-hf.q5_k_m.gguf

输出结果：

她将去中国，到一个没有互联网的地方。“我要去那里工作一段时间，把网络生活放在一边。”她说。 [end of text]

如果要交互式聊天， 需要添加一些参数， 示例如下：

llama.cpp/main -m ./models/chinese-llama-2-13b-hf.q5_k_m.gguf -c 512 -b 1024 -n 256 --keep 48 \
    --repeat_penalty 1.0 --color -i \
    -r "User:" -f prompts/chat-with-teacher.txt

llama.cpp/main  --interactive-first \
  --model ./models/chinese-llama-2-13b-hf.q5_k_m.gguf \
  --temp 0.2 \
  --keep -1 \
  -f prompts/chat-with-baichuan.txt \
  -r "用户:"

llama.cpp/main  --interactive-first \
  --model ./models/chinese-llama-2-13b-hf.q5_k_m.gguf \
  --temp 0.2 \
  --keep -1 \
  -f prompts/chat-with-teacher.txt \
  -r "\n学生:"

运行模型的时候， 在 GPU 历史窗口， 可以看到显卡是拉满的， 截图如下：

服务端

llama.cpp 还提供了与 open-ai 兼容的服务端 llama.cpp/server， 使用示例如下：

llama.cpp/server --host 0.0.0.0 --port 8080 \
  --ctx-size 2048 \
  --n-predict -1 \
  --model ./models/codellama-7b-instruct-hf.f32.gguf

服务端运行起来之后， 就可以脱离命令行， 进行 API 调用或者使用 Postman 之类的 http 测试工具进行测试。

Web 客户端

llama.cpp/server 默认的界面非常简单， 只能说是测试用， 用浏览器访问 http://localhost:8080/ 可以看到， 这里就不截图了， 太丑。

但是， llama.cpp/server 提供的 API 是与 open-ai 兼容的， 很多第三方的 ChatGPT 客户端都可以使用， 比如 ChatGPT-Next-Web ， 稍微查看了它的说明， 只要调整一下参数就可以直接运行它的 Docker 镜像， 无需任何修改：

docker run -it --rm \
  --name chatgpt-next-web \
  --publish 3000:3000 \
  --env OPENAI_API_KEY=1234567890 \
  --env BASE_URL=http://192.168.3.232:8080 \
  yidadaa/chatgpt-next-web

• 服务端使用运行 codellama-7b-instruct ， 在客户端询问代码相关的问题， 截图如下：

  

• 在服务端运行 01-ai/Yi-34B-200K ， 在客户端询问常规问题， 截图如下：

  

在操作 Linux 服务器时， 经常需要同时使用多个命令， 比如开着 htop 查看服务器负载， 同时调整配置等。虽然可以使用高级的客户端终端 (iTerm2, Microsoft Terminal) 同时建立多个连接到服务器， 但是有些服务器需要二次认证， 甚至不允许一个帐号进行多个连接，同时连接有的时候也会很不方便。 所以在服务器的终端内进行分屏也是有一定需要的。 GNU Screen 可以说是终端分屏/多任务的利器， 而且大多数的 Linux 服务器默认安装， 至少也是在默认的软件源中， 不需要添加第三方源， 安装与使用非常方便。

工作模式

Screen 的工作模式类似于 vim/vi 编辑器， 可分为操作模式和命令模式：

• 操作模式： 在此模式下，可以正常的输入各种指令， 和普通的 Shell 差不多；
• 命令模式： 在操作模式下， 按 Ctrl + A 就会进入命令模式， 可以实现终端分屏、断开会话、重连会话以及在多个会话中切换等操作；

后台命令

Screen 最常用的操作之一是执行后台命令， 常见的数据备份与同步命令， 往往执行的时间会比较长， 就可以使用 Screen 来执行， 示例步骤为：

1. 在终端中直接输入 screen ， 就会自动创建一个新的会话， 并进入这个会话；
2. 在会话可以执行任意 shell 命令， 比如 htop ；
3. 在 Screen 会话中按快捷键 Ctrl + A d ，即可断开当前会话， 第 2 步输入的命令会继续在后台执行， 当前窗口恢复到输入 screen 命令之前的状态；

4. 输入 screen -ls 可以查看所有的会话， 输出如下：

   

5. 再次输入 screen -r [session name] 即可恢复对应的会话状态；

利用 screen 来执行后台命令非常的方便，而且可以随时恢复会话状态， 查看执行状况。

如果不需要查看执行状态， 单纯的是后台命令则可以使用 Sub Shell 来执行。

终端分区

终端分区才是 screen 的强大之处， 可以将一个终端分成多个区域。 现代化的软件 (iTerm2, Microsoft Terminal, VSCode, Sublime 等) 都提供了分屏的功能, 让用户可以同时处理多个文档或多个任务。 screen 则可以在同一个终端内实现屏幕分区， 且各个分区相互独立， 互不干扰。

要使用屏幕分区， 就要掌握 screen 的命令模式， 这个与 vi/vim 的工作模式很类似， 如果熟悉 vi/vim 的话， 将会有非常熟悉的感觉。

1. 准备工作

   打开命令终端， 输入 screen 命令， 得到如下提示，

   

   然后按空格键或者回车键即可。

2. 水平分区

   在 screen 创建的终端中， 按 Ctrl+A ， 再按 Shift+S ， 即可水平分区， 如下图所示：

   

3. 垂直分区

   在 screen 终端中， 按 Ctrl+A ， 再按 Shift+\ ， 即可垂直分区， 如下图所示：

   

4. 切换活动分区

   现在创建了多个分区， 但是光标还在第一个分区内， 要切换分区， 则需要快捷键 Ctrl+A ， 再按 Tab ， 就会切换到下一个分区， 如果要继续切换， 则需要再次按 Ctrl+A 和 Tab 。

   

   如果切换到的分区还没有创建会话， 则需要按快捷键 Ctrl+A ， 再按 c 即可创建会话。

   

5. 关闭分区

   推出会话之后， 分区还在， 如果要关闭分区， 则需要按快捷键 Ctrl+A ， 再按 Shift+X 即可。

配置文件

可以使用 $HOME/.screenrc 文件对 screen 命令进行自定义配置， 而且网上已经有很多网友分享的配置文件。

GNU Sceren 是一个在终端内分屏的软件， Win/Lin/Mac 都可以运行， 熟练了之后，感觉可以把 iTerm2 给删掉了。