外币兑换1. 先说清楚AIRI能干什么，搞懂需求再动手
最近在Windows 11上折腾AIRI，前前后后花了整整三天，踩了不少坑，也总结了不少经验。所谓AIRI，简单说是一个本地AI推理与智能体开发环境框架，帮你把大模型调度、向量检索、工具调用管理这些东西封装成一套相对统一的基础设施，装好之后既能跑本地推理，也可以做后续的Agent开发。它的价值在于，你不需要自己去拼一堆散装组件，AIRI把这些东西串成了一条线，对个人开发者和转型做AI落地的团队来说，是很实用的一个基座。
不过话说回来，AIRI的官方文档说得太轻巧了，给人一种“一行命令装完就能跑”的错觉，实际上在Windows 11上装它，事情远没那么简单。光是环境前置就涉及WSL2、Docker Desktop、显卡驱动、CUDA、Python版本那一大堆东西，任何一个环节版本对不上，后面就是一堆莫名其妙的报错等着你。所以这篇踩坑指北，我把自己走过的弯路和最终的稳路都写出来，给准备在Windows 11上装AIRI的朋友一个参照。
这篇内容不是给纯小白看的教程，但只要你有一点点命令行基础和基础的环境变量概念，完全跟得上。我会把每一步为什么要这么做讲清楚，参数给出来，报错信息也直接贴上，方便你照着比对。适合谁看呢？想在本机跑AIRI做本地AI开发的人、想在Windows上搭一套可用的AI基础环境的人、以及和我一样被各种环境问题虐到怀疑人生的朋友。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：WSL2、Docker、显卡驱动一个不能少
2.1 检查Windows 11版本和虚拟化支持
很多人上来就直接装AIRI，一跑就报错，其实问题早就在操作系统这一层埋下了。AIRI对Windows 11的版本是有限制的，太老的版本不支持WSL2的完整特性，虚拟化平台也不一定默认开启。我在装之前没注意这一点，结果装到一半发现WSL2的内核更新失败，白白浪费了一个小时。
打开设置-系统-系统信息，先确认你的Windows 11版本号，建议至少是22H2以上。我现在用的系统是24H2，总体上稳定很多。除了版本号，还得确认CPU虚拟化有没有打开。任务管理器-性能-CPU，右下角可以看到“虚拟化”是不是“已启用”。如果没启用，得进BIOS把Intel VT-x或者AMD SVM打开。这个步骤很容易被忽略，但没开虚拟化的话，WSL2基本是跑不起来的。
还有一个细节，Hyper-V和虚拟机平台这两个Windows功能也需要启用。控制面板-程序和功能-启用或关闭Windows功能，把“适用于Linux的Windows子系统”和“虚拟机平台”勾上，确认之后重启。这一步做完，后面装WSL2就顺畅很多。别嫌麻烦，这层基础不打牢，后面全是连锁反应。
提示：如果你不知道怎么判断虚拟化，最简单的办法是直接在PowerShell里跑
systeminfo，看最后面Hyper-V要求那一段，如果提示“已检测到虚拟机监控程序”，说明虚拟化已经OK了。
2.2 启用WSL2的正确姿势
WSL2是AIRI在Windows上跑GPU加速的基础，因为ARM的容器机制和CUDA支持目前还是以WSL2为最稳路径。安装WSL2其实没那么玄乎，但有几个坑值得先说。
首先，千万别用老式的“启用适用于Linux的Windows子系统”之后再去手动下载内核更新包，那样走容易踩到内核版本不一致的坑。标准做法是直接用管理员身份打开PowerShell，执行 wsl --install。这个命令会自动把WSL2内核、虚拟化平台和默认的Ubuntu发行版一起装好，省去不少事。
在等待安装的时候，我做过一个错误示范：中途看到提示重启，重启完就忘了再执行一次 wsl --set-default-version 2。这个命令是确保以后创建的发行版都默认跑WSL2而不是WSL1。WSL1和WSL2虽然名字接近，但网络栈和文件系统性能差别很大，AIRI后续的容器和CUDA透传都依赖WSL2，所以一定要确认这一点。用 wsl -l -v 查看，如果VERSION那栏是2，就对了。
还有一个关键设置，很多人不知道，就是在Windows 11的C:\Users\用户名\.wslconfig文件里写内存和CPU限制。因为WSL2默认会用掉宿主机一半的内存，你要是机器内存不够，AIRI起容器的时候WSL2反而成了瓶颈。我的.wslconfig是这样配的：
ini复制[wsl2]
memory=12GB
processors=6
swap=4GB
localhostForwarding=true
memory 12GB是因为我本机32G内存，既要留给Windows一些余量，又要保证AIRI推理时有足够空间。processors设成6同样，别让WSL2把所有CPU吃满，不然后面宿主机会卡死。localhostForwarding=true这个很重，AIRI的Web管理界面是通过端口映射访问的，这个开关不开，你从Windows浏览器访问WSL2里的服务就会连不上。
配置完记得在PowerShell里执行 wsl --shutdown 再重新打开Ubuntu终端，让配置生效。这一步我踩过坑：改了配置没重启WSL2，折腾半天，服务一直起不来。
2.3 Docker Desktop安装与资源分配
接下来是Docker Desktop，这是AIRI容器化运行的关键依赖。AIRI的核心服务大部分以容器方式分发，所以Docker Desktop是绕不开的。下载安装包从Docker官网下就行，安装没什么难度，选项里不用改太多，但有一个地方要特别注意：安装过程中会让你选择是否使用Windows容器，一定不要选，维持默认的Linux容器。AIRI的镜像都是Linux的，选错模式后面拉镜像都会失败。
装完Docker Desktop之后，第一件事不是急着用，而是进设置-Resources-WSL Integration，把你安装的Ubuntu发行版开关打开。这个步骤的意义在于，让Docker在启动时把容器运行在WSL2后端，从而借助WSL2的GPU透传能力跑CUDA推理。我记得第一次装完Docker Desktop没开这个开关，AIRI启动时报了一大串GPU not found的错，界面直接起不来。
此外还有内存分配。AIRI默认跑起来要占大概4到6G内存，如果你同时在跑大一点的模型，内存分太小肯定会OOM。Docker Desktop的Resources默认是2G内存，必须调高。我自己的设定是8G内存，磁盘镜像大小默认就行，但确认你的系统盘至少剩30G以上空间，AIRI的镜像和模型文件真的不小。
GPU访问还要在Docker Desktop设置里勾选“启用GPU计算”那一项，这个选项在较新版本里默认是打开的，但建议还是去检查一下。如果机型是笔记本，记得进NVIDIA控制面板确认当前独显驱动的WSL2支持是正常的。驱动这块后面会详细说，这里先带过。
3. 正式开始安装：从拉取配置到首次启动
3.1 安装包和依赖的选择
环境就打到这里，终于可以进入AIRI本体安装了。先说结论：AIRI虽然提供了Windows原生安装器，但我个人实测下来，还是用WSL2 + Docker的方式最稳，后续升级和维护也省事。所以下面的步骤都是在Ubuntu终端里执行的。
进入Ubuntu终端之后，先别急着装AIRI，把基础工具链补齐。确保Python版本在3.10到3.12之间，因为AIRI对Python版本有要求，太新的3.13有些依赖还没跟上，太旧的3.9又缺类型特性。我一开始用的是系统默认的Python 3.8，结果装依赖的时候一堆包编译报错，后来装了个3.11的虚拟环境才算顺了。
推荐装一个conda，版本管理会轻松很多，哪怕不用conda，至少也要会用venv。我在/opt下面建了一个目录专门放AIRI的安装文件：
bash复制sudo mkdir -p /opt/airi
sudo chown $USER /opt/airi
然后从AIRI官方仓库拉取安装脚本。装这个的过程中我遇到的第一个坑是：直接跑安装脚本的时候，它默认会检测显卡驱动并尝试安装CUDA工具包。这里建议千万不要让它自动装CUDA，因为自动装的很可能是通用版本，跟你的驱动不一定匹配，容易把环境搞乱。正确做法是安装时加参数跳过驱动检测，我用的是：
bash复制bash install.sh --skip-cuda-env-check --prefix /opt/airi
--skip-cuda-env-check 这个参数不是常驻的，不同版本可能名字略有差异，具体可以用 bash install.sh --help 看一下。核心思路就是：CUDA驱动层的准备在自己手里控，不要让安装脚本帮你乱搞。另外--prefix是指定安装路径，避免它默认装到/usr/local导致后续权限问题。
3.2 初始化与配置文件调整
安装脚本跑完之后，AIRI的命令行工具就算落盘了。在正式启动之前，要先去改配置文件。AIRI的配置目录在~/.airi/config.yml，这个文件决定了它怎么连接存储、怎么分配模型缓存目录、要不要启用GPU推理。
我的配置是这样：
yaml复制runtime:
engine: docker
work_dir: /opt/airi/workspace
model_cache: /opt/airi/models
gpu:
enabled: true
device_ids: ["0"]
network:
host: 0.0.0.0
port: 18432
external_url: http://localhost:18432
runtime.engine选docker，跟前面的部署方式对应。model_cache建议放在一个独立目录，我是放在/opt/airi/models下，主要是模型文件动辄几十G，放一个固定位置方便清理。gpu.enabled必须开true，不然跑推理就是禁用CPU硬算，速度没法看。network.host设0.0.0.0是为了让WSL2里的服务能被Windows宿主机访问到，这个配合之前说过的localhostForwarding=true才能生效。
改完配置之后，先把PATH加一下。用的是普通用户的话，在~/.bashrc里加一行：
bash复制export PATH=/opt/airi/bin:$PATH
export AIRI_HOME=/opt/airi
source一下让环境变量生效，然后跑airi doctor。这个命令会检查当前环境是否满足AIRI的运行条件，检查项包括Docker是否正常、GPU是否可见、端口是否被占用等。这是个非常好的排错入口，任何一项标红，直接解决完再看下一步。
3.3 首次启动与验证
一切检查通过之后，执行airi start。第一次启动会自动去拉AIRI的核心镜像，这个下载过程取决于网络状况，如果网络不给力，可以在Docker配置里把registry mirror改成国内可用的镜像加速地址。这一步我倒是没踩坑，但看群里不少同行是卡在这儿的。
启动成功后，AIRI会输出一串服务地址。默认是http://localhost:18432，在Windows下直接浏览器访问这个地址就能打开管理界面。第一次打开界面，它会要求你创建一个管理员账号，这个步骤别用太简单的密码，因为AIRI的管理界面默认是暴露在0.0.0.0上的，局域网内其他设备也能访问到。
到这里，AIRI就算跑起来了。验证方式也很简单，在管理界面找到模型管理，拉一个小的模型下来做推理测试。但实际操作时，很多坑是从这个阶段才真正开始显现的。我下面单独开一章，专门把我在跑通前后遇到的问题逐个拆开说。
4. 踩坑实录：这些问题我基本都试了一遍
4.1 显卡驱动与CUDA不匹配
这是所有坑里最经典的一个。AIRI启动后第一次跑模型，控制台直接报CUDA error: no kernel image is available for execution on the device。这个报错的意思很明确：当前CUDA运行库与显卡驱动支持的内核不匹配，驱动里没有对应CUDA版本的kernel镜像。
我当时用的是NVIDIA GeForce RTX 4060 Laptop，驱动版本是560.xx，但容器里的CUDA是12.4，两者组合下来就撞上了。解决思路是，先看驱动支持的CUDA版本，在Windows的PowerShell里执行nvidia-smi，右上角有个“CUDA Version”，这个数字是当前驱动最高能支持的CUDA版本。一定要确保容器内的CUDA版本不大于这个数。
然后还要检查WSL2里看到的GPU是否正常。进入Ubuntu终端跑nvidia-smi，如果提示无法连接，说明WSL2的GPU透传有问题。此时应该回到Windows下更新驱动，再到Docker Desktop确认WSL Integration状态。如果在WSL2里能正常看到GPU，但Docker容器里始终报错，那你需要把Docker Desktop的GPU服务重启一次，我就是重启完就正常了。
注意：驱动更新后一定要执行
wsl --shutdown再重启，因为WSL2持有的驱动句柄不会自动刷新。
4.2 WSL2内存不足导致启动失败
第二个高频故障是启动AIRI时服务直接崩溃，日志里出现cannot allocate memory，甚至Docker容器直接显示OOMKilled状态。我一开始以为AIRI的容器内存配额不够，其实根源在WSL2本身的内存上限。
前面说了.wslconfig里memory可以手动设置。默认WSL2内存上限是宿主机总内存的50%，如果你机器是16G内存，实际WSL2只有8G，跑AIRI加一个大模型基本就满了。解决的办法就是重设上限。我把memory调成12G之后，情况缓解了很多。
但这里有个细节要注意，wslconfig里memory不是设得越大越好，WSL2和Windows共享物理内存，WSL2占太多，Windows那边一旦跑大程序就卡成幻灯片。合理的做法是，给WSL2设定一个固定值，并给swap留一点余量。我用的是12G内存加4G swap。如果你用的是32G内存的机器，可以设16G，但别全给。
4.3 模型下载超时和网络问题
装好AIRI之后，在管理界面拉模型，经常卡在下载进度条，甚至报connection timed out。这并不一定是AIRI的问题，而是模型仓库在国内的连通性不好。便宜的办法是配置镜像加速。不同镜像仓库的地址不同，不能一概而论，但思路是一样的：找到可用的镜像源，写进AIRI的下载配置文件里，让它从镜像源拉取。
在~/.airi/config.yml里，模型下载相关配置可以改成：
yaml复制model:
registry: hf-mirror
timeout: 300
retries: 3
这里model.registry是在AIRI内置的镜像选项里选一个速度最快的。不同地区网络状况不一样，你可以多试几个镜像源，哪个快用哪个。timeout建议至少300秒，因为大模型文件动辄好几个G，超时设短了反而容易中断下载。
如果你是在局域网里跑，还可以用已有的代理通道下载模型文件，然后手动放到model_cache目录里，再在管理界面刷新，AIRI会自动识别本地缓存。这个方法最稳，适合那些下载了多次都失败的大模型。
4.4 文件路径与权限导致的诡异报错
AIRI在Windows上打印的报错信息有时候极其不直观，比如启动后提示/data: Read-only file system，或者是权限不足导致的无法加载模型文件。这种问题在Windows原生安装方式里更常见，因为Windows的盘符路径和WSL2的Linux路径之间转换经常出问题。我切换到WSL2 + Docker方式之后，这类报错少了很多，但并不是完全消失。
在WSL2里跑AIRI，模型缓存目录如果在Windows的挂载盘（比如/mnt/c/...），那么每次读写都要经过9P协议，一方面性能很拉胯，另一方面权限映射容易出问题，container里访问外部目录经常只能读不能写。所以一个基本原则是：AIRI的工作目录和模型目录，一定要放在WSL2自己的虚拟磁盘里，不要放在/mnt/c、/mnt/d这些Windows挂载路径上。
我后来把work_dir和model_cache全部改到/opt/airi下面，再配合docker的volume映射，权限问题就再也没出现过。如果你已经不小心把模型放在/mnt/c下面了，最简单的办法是复制到WSL2的目录再改配置：
bash复制mv /mnt/c/Users/你的用户名/models /opt/airi/models
然后确保/opt/airi/models目录归属当前用户：
bash复制sudo chown -R $USER:$USER /opt/airi/models
别小看这个权限问题，AIRI容器内是以非root用户运行的，如果宿主机的目录权限是root所有但没开放写权限，容器去写模型缓存就会报没权限。
4.5 Docker容器端口映射不生效
这个问题我排查了很久，现象是AIRI在WSL2里正常启动，日志也显示服务起来了，但从Windows浏览器访问localhost:18432就是连不上。如果你拿到的是0.0.0.0:18432的监听地址，本地访问还是不通，那大概率是Docker的localhost转发坏了。
解决前先确认WSL2里服务本身是不是真的能访问。在Ubuntu终端里执行：
bash复制curl http://localhost:18432/health
如果返回正常，说明AIRI本身没问题，问题出在WSL2和Windows的端口转发上。此时在PowerShell里检查一下转发规则：
powershell复制netsh interface portproxy show all
如果转发规则丢失，或者里面指向的IP已经变了，那就删掉重新加。更快的办法是直接重启WSL2和Docker Desktop，让端口转发机制重新建立。我用的命令是：
powershell复制wsl --shutdown
& 'C:\Program Files\Docker\Docker\Docker Desktop.exe'
等Docker Desktop重新启动后，再跑airi start。这里有个技巧，如果发现WSL2的IP地址变了，不要修改配置去迁就它，就让Docker Desktop的localhostForwarding机制自动处理，改外部访问地址反而会把问题搞复杂。
5. 跑起来之后顺手做的几件事
5.1 确认GPU真的被容器用上了
安装跑通不等于GPU加速就生效了，很多情况下AIRI界面能打开，但实际上在拿CPU硬算。判断方法很简单，跑一个推理任务的同时，打开任务管理器-性能-GPU，观察利用率是不是有波动。如果GPU利用率一直在个位数徘徊，而CPU却爆满，那很可能容器没拿到GPU。
此时可以进容器里执行一个简单验证。先查看AIRI容器的名字：
bash复制docker ps | grep airi
然后进入容器跑nvidia-smi：
bash复制docker exec -it <容器ID> nvidia-smi
如果提示找不到nvidia-smi或GPU不存在，说明容器的运行时不是NVIDIA Container Toolkit。AIRI启动时的GPU支持依赖于Docker的nvidia runtime。需要检查Docker Desktop设置里GPU相关选项是否打开，并确认/etc/docker/daemon.json里配置了nvidia运行时。整体上只要Docker Desktop启用GPU计算，AIRI内部会自动使用，但如果自行改过Docker配置，就可能把这层关系弄坏。
5.2 开机自启与日常维护
AIRI不是装完就不管了，它是有后台服务的，但重启电脑之后服务可能不会自动起，尤其WSL2默认就是随Windows启动的，可Docker Desktop不一定。我建议把Docker Desktop设置成开机自启，在Docker Desktop的Settings-General里勾选“Start Docker Desktop when you sign in to your computer”。
AIRI服务本身可以配置成开机自启，在Ubuntu里用systemd用户服务最简单。在~/.config/systemd/user/airi.service写一个服务文件，内容大致如下：
ini复制[Unit]
Description=AIRI Service
After=docker.service
[Service]
ExecStart=/opt/airi/bin/airi start
ExecStop=/opt/airi/bin/airi stop
Restart=on-failure
[Install]
WantedBy=default.target
然后执行：
bash复制systemctl --user enable airi
systemctl --user start airi
注意要先执行loginctl enable-linger $USER，否则用户服务在没登录的情况下不会启动。这个设置对你如果想把AIRI当本机常驻服务用，非常有用。
日常维护就三件事：更新AIRE版本时，先备份config.yml和模型缓存路径下的目录结构；清理Docker无用镜像时小心删错，用docker image prune不会删正在运行的容器；注意磁盘占用，模型越多磁盘越容易满，提前规划好模型缓存目录的大小。
5.3 后续还能怎么玩
AIRI跑起来之后，基本能力是调用本地模型做推理，再往上你可以按它的插件机制加一些Agent组件，比如基于工具调用的代码解释器、联网搜索器、定时任务调度器。这些组件在没有AIRI之前，你要自己拼装环境、管理依赖和进程，现在一个服务就能挂上，开发路径会顺很多。
我个人在实际使用中体会最深的一点是：AIRI这类工具，真正的门槛其实不在软件本身，而在于“运行环境是否干净”。踩了这么多坑之后，我现在装任何类似的东西都养成了这个习惯：先检查系统、驱动、虚拟化、容器运行时，再装软件本体。Windows 11叠加WSL2这套组合，只要环境层面理顺了，AIRI跑起来意外的省心，模型下载快、GPU利用率高、Web界面响应也流畅。后面不管是继续本地调试模型，还是接智能体开发，这个基座基本都够用。希望这篇含泪总结能帮你少走几个钟头的弯路。