龙芯LoongArch平台安装芯语CAP：AI应用一站式部署指南

前一阵收到一台龙芯工作站的测试任务系统是统信UOS处理器是龙芯3A6000。任务本身不复杂——在这台机器上跑几个日用AI应用比如聊天助手和本地文档摘要工具。但真正动手之后才发现龙芯的LoongArch架构虽然跑桌面、跑办公软件都已经很流畅AI这块却一直缺一个像样的“一站式入口”要么手动编译源码要么面对一堆不兼容的二进制依赖。直到我在官方源里发现了芯语CAP龙芯AI应用商店才算是找到了一个能正经解决“在龙芯上玩AI”的办法。这篇文章就把我这几天的完整安装和使用过程分享出来尤其是新手容易踩坑的地方希望做一份可以直接照着操作的指南。如果你手上有龙芯3A系列处理器的主机想在上面装AI聊天、文生图、代码辅助这类应用或者想让本地跑一个大模型做开发测试这篇对你适用。1. 先搞清楚芯语CAP是什么以及为什么龙芯用户需要它1.1 龙芯平台上的AI软件生态卡在哪里龙芯的LoongArch指令集是自主设计的和x86、ARM都不兼容。这带来一个最直接的后果主流AI社区里那些编译好的二进制包、预构建的wheel、现成的AppImage在龙芯上基本都跑不起来。AI应用偏偏又是软件世界里依赖最重的类别——Numpy、ONNX Runtime、PyTorch、量化推理引擎、tokenizer库一串一串的底层依赖任何一个版本对不上整个应用就启动失败。我见过有人为了装一个智能问答工具手动编译了整整一个下午的依赖库到最后跑起来还因为glibc版本不对直接闪退。这就是龙芯平台AI应用分发的核心矛盾不是硬件不行而是软件分发的模式太痛苦。龙芯3A6000的纯CPU推理性能跑起7B量级的量化语言模型是完全够用的关键是怎么把“从源码到能跑”的漫长链条压缩掉。1.2 芯语CAP做的事情把AI应用变成“一键安装”CAP本质上是一个面向LoongArch平台的AI应用聚合平台。它的工作机制可以理解成“手机应用商店 Linux包管理器”的结合体统一定义应用的依赖关系把龙芯适配版的运行时比如LoongArch版推理引擎打包好用户不需要自己找集中管理模型文件所有应用从统一模型仓库拉取量化模型同一个模型多个应用可以共用一份提供沙箱和权限管控第三方AI应用不能随意读写用户目录统一升级入口应用商店里点一下“升级”依赖和应用一起更新不会出现升级完应用然后底层库崩了的尴尬整个设计思路其实很朴素把复杂度从用户身上移走放进平台维护的仓库里。用户不需要知道LoongArch版推理引擎是从哪来的也不需要处理环境变量和LD_LIBRARY_PATHCAP负责把这些细节藏起来。1.3 凭据与适用人群这篇指南写给谁我写这篇依据的实测环境是一台龙芯3A6000、16GB内存、512GB NVMe SSD的机器系统是统信UOS 1070。我在上面装了当前版本的CAP并陆续安装了对话、文生图、文档总结三类应用每一条都实际跑过。适合的读者有三类刚入手龙芯主机还没找到AI生态入口的新用户想在国产平台上跑本地大模型的开发者以及给信创设备做软件预研的朋友。如果你只是对CAP好奇、手头还没有龙芯设备也可以当作一份预研笔记来读。2. 安装前的硬件与系统准备这些检查项千万不要跳过2.1 硬件规格与空间底线用途内存存储可用空间建议处理器轻度应用对话、文档摘要8GB起步30GB龙芯3A5000及以上标准应用文生图、本地模型API服务16GB100GB龙芯3A6000大模型长时间推理7B~13B量化模型32GB200GB龙芯3A6000或更高这里说的存储是模型文件加应用安装包的合计。大语言模型的权重动辄十几个GB7B的Q4量化模型大约4到6GB13B的Q4量化大约8到10GB文生图应用还有额外的权重文件。如果你打算把模型装在系统盘建议至少留出50GB以上的余量不然装到第三个应用就可能卡在空间不足上。内存比磁盘更要紧。纯CPU推理时模型权重要全部加载进内存内存不够就直接加载失败这不是“卡一下”的问题是直接OOM。我的建议很直接想在龙芯上流畅跑13B级别的量化模型16GB是底线32GB会更从容。2.2 操作系统与内核版本检查芯语CAP对操作系统的要求不算苛刻本质上是用户态软件集合只要是LoongArch架构的现代Linux发行版基本都能装。我在统信UOS 1070和Loongnix 2.0上都实际装过麒麟V10在社区也有成功反馈。关键在内核版本。建议内核至少5.10以上因为部分依赖库在高版本内核下对龙芯的页大小和向量指令优化支持才完整。查看系统信息用这个命令uname -a注意输出的架构信息里应该能看到loongarch64。如果显示的是mips64说明这是早期龙芯3A4000平台那套环境对当前版本CAP的适配可能不完整建议先去社区确认有没有对应的旧版本。这一步别偷懒我见过有人拿老平台硬装新版最后应用商店界面起不来折腾半天才发现是架构标识不匹配。2.3 基础组件安装证书和下载工具不能缺CAP安装时会自动处理大部分依赖但有几个基础组件建议提前装好否则安装过程会卡在依赖阶段。以我实测的统信UOS为例sudo apt update sudo apt install wget curl ca-certificates gnupg lsb-release这几个是下载、证书、密钥管理的基础工具。尤其ca-certificates很重要首次初始化CAP时它需要从源服务器拉取仓库元数据和公钥如果系统证书库不完整HTTPS握手会失败报错信息看着像网络问题实际却是证书问题——这个坑后面排错章节我会细说。如果你用Loongnix包管理器命令同样适用因为底层也是Debian系。2.4 安装前的三个预检命令我建议在装CAP之前先跑一遍下面三组命令把机器状态记录下来后面排错时用得上uname -m # 确认架构 free -h # 确认实际可用内存 df -h /var # 确认系统分区剩余空间为什么要记录CAP的应用商店会往缓存目录写中间文件如果系统分区太小安装中途会报“空间不足”。之前我就见过一台机器根分区只有20GB装完系统已经用了18GB结果CAP装了20分钟最后在写模型缓存时报错。建议分区紧张的话先处理分区不要等报错再停工折腾。3. 完整安装流程拆解从下载到第一条AI应用跑起来3.1 添加软件源并导入密钥CAP的安装包分发方式我实测有两种一是从官方渠道下载安装包手动装二是把CAP软件源添加到系统源列表直接走apt安装。我推荐第二种因为后续升级省事应用商店能跟着系统源一起更新。以通用方式为例先导入官方公钥curl -fsSL https://cap-source.loong.cn/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cap-archive-keyring.gpg然后添加源列表不同版本源的地址可能变化以你安装时官方文档给出的一行为准大致格式如下echo deb [signed-by/usr/share/keyrings/cap-archive-keyring.gpg] https://cap-source.loong.cn/stable loongarch64 main | sudo tee /etc/apt/sources.list.d/cap.list sudo apt update执行完apt update如果能看到cap相关源正常加载源配置就没问题。这一步最常见的两个错误gpg密钥路径写错导致签名校验失败以及源文件格式里少了架构标识导致apt完全忽略。别凭记忆敲命令直接复制官方文档里那一行最稳。3.2 GUI入口还是纯终端其实两者都要安装完成后系统里会出现两个入口一个图形图标通常叫“芯语AI应用”一个命令行工具cap。初次使用我建议先开终端跑一遍cap --version确认CLI可用cap --version看到版本号说明核心CLI已经就位。之后去菜单里打开图形入口完成首次初始化。首次初始化会做几件关键的事创建应用目录默认在~/cap和模型目录默认在~/cap/models生成用户配置文件~/.config/cap/config.toml初始化应用商店数据库索引这个过程大约需要1到3分钟期间界面可能看起来静止不要强制关闭。如果超过10分钟还没结束再考虑排查网络或源的问题。我知道有人等不及就杀进程结果配置文件写到一半损坏后面再启动一直报错只能删了配置重新初始化。3.3 设置存储路径把模型目录挪到大分区首次初始化时会让你选“应用安装路径”和“模型缓存路径”这一步是新手最容易忽略但最影响体验的。我的建议应用安装路径保持默认装到用户目录即可模型缓存路径务必指定到一个空间足够大的分区用我那台机器举例系统盘200GB另挂了一块2TB数据盘模型目录我设置成/data/cap-models。好处是以后下载大模型完全不用担心系统盘被塞满而且模型文件是可复用资产换系统时只需把模型目录挂回去cap model list就能识别省下重新下载的时间。设置完成后配置文件里对应字段大约是这样[storage] model_dir /data/cap-models app_dir /home/user/cap/apps3.4 安装第一个AI应用观察依赖自动处理的过程应用商店界面左侧有分类对话助手、图像生成、文档处理、代码辅助、视频理解等。我建议第一个应用装“对话助手”类入口最简单验证链路最短。点“安装”后会弹出进度条。如果你注意观察会发现它下载的不只是应用本身还会顺手拉一批共享运行时比如cap-runtime-ggml-loongarch64、cap-runtime-onnx这类包。这正是应用商店模式的价值同一个推理运行时对话应用和文档应用共用不重复下载。实测从点击安装到应用图标变为“打开”大约5到10分钟取决于网速和运行时包大小。这一步网络必须稳定因为有些包从镜像源拉取中断后虽然能续传但偶尔会卡在99%不动需要手动点一次“重试”。3.5 验证第一个应用真的可用安装完成后从应用详情页点“打开”第一次启动会要求接受隐私协议然后进入类似聊天软件的界面。先别急着提问我建议做三件事在设置里看模型名称确认当前加载的是适配版发一条“你好”确认基础对话通畅打开系统监视器确认一个推理进程常驻内存占用和模型大小对得上三步都正常这台龙芯机器上的AI环境就跑通了。然后可以用CLI再验证一次cap list apps这会列出所有已安装的应用包含版本号和运行状态。到这里一个可用的芯语CAP环境就算真正搭好了。4. 把AI应用真正用起来模型下载、对话、开发接口的日常操作4.1 模型下载别一股脑全装按需拉取商店里的AI应用大多不内置模型模型是单独从模型源下载的。这是CAP比较聪明的地方同一个模型如果三个应用都能用就只需下载一份由平台统一管理。命令行下载模型用cap model pull deepseek-r1:7b-q4cap model pull后面接模型名加标签q4是量化格式f16是半精度原始格式。日常对话选7B的Q4量化质量足够且内存压力小文档总结或复杂推理可以试试13B的Q432GB以下内存的机器不建议拉超过30GB的模型加载阶段就很吃力。下载过程中随时用cap model list查看进度和占用空间。我建议始终保持一到两个常用模型驻留不要一次下十几个又占磁盘又增加模型管理器扫描时间。4.2 三种使用模式GUI、本地API、命令行管道跑通基础对话后CAP的价值会体现在“以多种方式调用AI能力”上模式一图形界面直接聊天。适合日常提问、查看历史记录。对话记录默认存在~/cap/chat-logs按日期分文件保存备份非常方便。模式二本地API服务。CAP内置了一个与主流接口风格兼容的本地推理服务。启动方式cap serve --model deepseek-r1:7b-q4 --port 8080启动后任何支持HTTP调用的程序都可以把请求发到http://127.0.0.1:8080。我用Python写脚本调用时请求体大概是这样import requests resp requests.post( http://127.0.0.1:8080/v1/chat/completions, json{ model: deepseek-r1:7b-q4, messages: [{role: user, content: 用三句话概括龙芯AI生态的发展脉络}] }, timeout180 ) print(resp.json()[choices][0][message][content])这是把CAP当成一个本地大模型服务来用适合自动化脚本和开发测试。端口默认只监听127.0.0.1不要开放到局域网避免别的主机上的程序直接访问你的模型接口。模式三命令行单次问答。适合脚本化处理比如每天定时让模型整理日志cat error.log | cap run --model deepseek-r1:7b-q4 把这段日志按错误类型归类输出是纯文本可以直接重定向到文件。我实际用下来比开图形界面再复制粘贴高效太多尤其是批处理场景。4.3 多应用协同与资源管理装了多个AI应用后会遇到“同时开好几个模型”的问题。CAP的处理方式是每个应用在后台启动独立推理进程共享一个运行时管理服务。在应用商店首页有“资源占用”标签能看到每个进程的内存占用。我实测同时运行一个7B对话模型和一个文生图应用内存大约吃掉10GB左右16GB机器仍有余量。但如果你用的模型比较大建议只保留主用模型常驻其他应用用完就关。有个小技巧在应用详情页的“启动策略”里把不常用应用设为“按需启动”这样它不会常驻内存首次打开时多加载几秒换来的是平时几乎不占资源。4.4 配置项里的门道线程数、上下文长度、温度每个模型详情页有三个高级配置项对龙芯纯CPU推理很关键线程数默认是CPU核心数的一半。纯CPU推理时线程数不是越高越好内存带宽是瓶颈。龙芯3A6000是8核心我实测设6线程比8线程有时更快因为给系统留了两个核做IO和显示。建议从核心数减2起步试用一条中等长度的问题测三次取平均响应时间。上下文长度默认4096通常够用文档总结场景可以调到8192但内存占用会显著上升。7B模型在4096上下文时大约额外多占1到2GB内存。温度日常对话0.7左右代码生成建议0.2。这是AI应用常识但新手可以在详情页随手改改感受一下对回答风格的实际影响。5. 装完别急着走排查过的高频问题与性能调优心得5.1 安装源配置了却提示“找不到软件包”这个大概率是apt update没把新源缓存进来。先跑一遍sudo apt update看输出末尾有没有cap相关的Hit或Get行。如果没有检查/etc/apt/sources.list.d/cap.list里的URL是否重复了sources.list里的内容或者源文件里漏了架构声明。我遇到过具体案例deb [signed-by...]后面直接跟URL忘了写loongarch64 mainapt一直报“无法定位软件包”。补上发行版代号之后问题立刻消失。deb格式里signed-by和URL之间有没有空格都可能影响解析建议严格按官方文档的格式复制。5.2 应用商店界面打开是白屏这是新手最慌的坑。先说结论90%情况不是显卡驱动问题而是商店的前端组件没加载完全或本地缓存损坏。按顺序试cap repo update cap doctorcap doctor会检查关键目录、权限、依赖库版本。如果它报了某个.so文件找不到多半是安装时依赖顺序错乱重新执行sudo apt --fix-broken install可以补救。如果诊断全绿还白屏删掉~/.cache/cap清一下前端缓存重启商店。不要一上来就重装系统——这个坑很容易误判我在社区见过有人为此把系统重装了一遍结果问题依旧根因就是缓存目录权限普通用户没有写权限而已。5.3 模型下载到一半报错“校验失败”下载途中失败最常见原因是网络源抖动导致文件不完整。CAP下载模型时会做完整性校验校验失败会报错这是保护机制不代表模型本身有问题。解决办法是重新拉取一次cap model pull deepseek-r1:7b-q4 --resume如果连续两次都在同一个百分比失败建议清掉缓存再全量下载cap model remove deepseek-r1:7b-q4 --purge cap model pull deepseek-r1:7b-q4还有一个常被忽略的点模型下载时不要同时跑大型任务。磁盘顺序读写被抢占会导致下载超时。我在一次下载大模型时正在跑批量文档处理连续失败三次停掉任务后再下就一次成功。5.4 加载模型时提示“无法分配内存”这个提示有两种情况。一种是真的物理内存不够。13B的Q4量化模型加载时大约需要10GB内存加上系统本身占用16GB内存机器可能只剩不到6GB可用。解决办法要么换7B模型要么临时关掉几个应用释放内存。另一种是系统开启了太多内存页面缓存。Linux的page cache会占用大量“看起来已用”的内存但实际可回收。CAP加载模型时如果遇到内存不足会尝试回收缓存但极端情况下比如同时开着浏览器几十个标签页仍然会失败。这时候可以运行sudo sync echo 3 | sudo tee /proc/sys/vm/drop_caches然后再启动应用通常就能过了。这个命令在内存紧张时临时有效不要频繁使用。5.5 针对龙芯平台的小优化心得纯CPU推理场景下下面几个调整是我实测有效果的龙芯3A6000的8个核心跑推理时设置线程数为6响应速度反而略快因为IO线程和界面不再抢CPU。如果系统里同时跑图形界面模型上下文保持4096即可过高的上下文会让响应时间成倍增加纯CPU推理下体感特别明显。Q4_K_M量化的模型比Q8在速度上优势明显质量差距在对话场景几乎感知不到但如果做代码生成这类对精度更敏感的任务再考虑Q8。模型预热很重要。刚启动的推理进程看似就绪实际上权重仍在从磁盘映射到内存第一次提问会特别慢。先发一条“你好”等模型状态变为“运行中”再开始正式提问。5.6 常见问题速查表症状可能原因处理方式安装时提示找不到软件包源列表格式问题或未update检查cap.list格式执行apt update应用商店白屏前端缓存损坏执行cap repo update、cap doctor清理~/.cache/cap模型下载校验失败网络抖动导致文件不完整用--resume续传仍失败则purge后重新拉取加载模型OOM内存不足或page cache挤压关闭不用的应用必要时释放缓存对话响应太慢线程数不合适或模型偏大调线程数到核心数减2换Q4量化模型应用打开后空白无提示模型尚未加载完成等待1到2分钟观察系统监视器是否有推理进程好了这就是我这次在龙芯平台上从零安装芯语CAP并把AI应用真正跑起来的全过程记录。总结起来其实就三句话先把预检和源配置做扎实安装过程别手动干预遇到问题先跑cap doctor不要轻易重装。最后再分享一个我这几天的使用心得新手最容易犯的错误是觉得“内存越大越好”一上来就拉最大的模型结果跑不起来又怪平台。我的建议是先从7B Q4这种“够用不重”的档位开始把整个流程走通再去挑战更大的模型。龙芯的AI生态现在确实还在起步阶段但像芯语CAP这种把复杂度藏起来、让用户能直接点开应用就用的思路方向是对的。如果你也是龙芯用户不妨装上试试跑通第一个AI应用之后你会觉得这台机器能做的事比想象中多很多。