1. 芯语 CAP 到底解决了什么问题

先说结论：芯语 CAP 是一款面向龙芯平台（LoongArch 架构）的 AI 应用分发与运行环境管理工具。你可以把它理解成“龙芯电脑上的 AI 软件管家”＋“一键部署套件”的结合体。

龙芯平台这几年进步很大，但生态短板一直存在——尤其是 AI 应用这块。你拿到一台龙芯机器，想跑个本地大模型、想装个 OCR 工具、想试试语音转写，往往要手动编译依赖、解决 Python 版本冲突、折腾虚拟环境，一套流程下来少则半天多则两三天，中间随便一个依赖编译失败，心态直接崩。

我之前在一台龙芯 3A6000 上装过某个开源语音识别项目，光是编译音频处理库就花了一个晚上，最后还因为 glibc 版本不匹配直接弃坑。这不是个例，而是龙芯用户普遍面临的真实痛点。

芯语 CAP 的定位就是把这一堆脏活累活揽到自己身上：它内部整合了针对 LoongArch 架构预编译好的运行环境、常用 AI 框架适配层，以及应用仓库。你不需要知道底层依赖长什么样，只需要在商店里找到应用，点安装，剩下的环境配置、路径设置、启动脚本生成，它全帮你搞定。

说几个最实用的场景，你就明白这东西能吃多少饭：

• 本地大模型对话工具：想在龙芯机器上跑 ChatGLM、通义千问开源版这类模型，普通装法要折腾 CUDA 兼容层（龙芯搭配的是 GPU 或算力卡），CAP 直接给你配好推理引擎和模型管理。
• 办公提效类 AI：文档摘要、OCR 识别、表格结构化抽取，这一类工具在普通 x86 机器上装起来都费劲，在龙芯上更是地狱难度。CAP 仓库里直接打包好，装完即用。
• 开发测试环境：你是一个开发者，想在龙芯机器上测试 AI 应用，CAP 可以帮你创建隔离的运行空间，不会搞乱系统自带的 Python。

所以这篇文章就是写给谁看的？三类人：刚拿到龙芯主机想装 AI 工具但被命令行劝退的新手；要在龙芯平台做 AI 应用验证的开发者；负责信创终端运维、需要批量部署 AI 工具的 IT 人员。下面所有内容，都是我实际动手操作后的经验总结，步骤按顺序走就行，不需要你有太多 Linux 基础。

2. 安装前的环境检查，这一步千万别跳

很多新手拿到安装包就直接敲命令，结果折腾半天发现是系统版本不匹配或者缺了关键组件。我建议你在动手之前，花五分钟把下面几项确认清楚。

2.1 确认 CPU 架构和系统版本

芯语 CAP 是专门针对龙芯 LoongArch 架构做的适配，所以你的机器必须是龙芯处理器。可以先跑一条命令确认：

uname -m

如果你看到输出是loongarch64，那没问题，架构匹配。如果输出的是x86_64或aarch64，那说明你当前不是龙芯原生系统，要么是用了转译环境，要么是机器不对，这种情况后面装起来会遇到诡异的问题，建议先解决系统层面的问题再继续。

接下来看系统发行版和版本：

cat /etc/os-release

目前芯语 CAP 对统信 UOS、麒麟（Kylin）、Loongnix 这几个主流龙芯系统的兼容性比较好。我实测的环境是一台龙芯 3A6000 处理器的主机，系统是统信 UOS 1070 版本，内核 6.1 以上，全程没有遇到兼容性报错。如果你用的是社区版的 Loongnix 或者 Debian 的 LoongArch 移植版，理论上也能装，但建议先用上述三个系统之一，省心不少。

2.2 检查磁盘、内存和显卡驱动

AI 应用商店里的应用，尤其是涉及模型推理的，对资源有一定要求。我建议的最低配置如下：

重点强调一下显卡驱动的问题。龙芯平台目前常见的有两类硬件方案：一类是只靠 CPU 推理，这种情况不需要额外装驱动，但速度会慢一些；另一类是搭配了国产 GPU 或通用算力卡，比如摩尔线程、芯动科技这类，这种情况一定要先装好厂商提供的驱动。我遇到过不止一次，CAP 装完了模型也能下，但一跑 prompt 就报Cannot load libcuda.so.1之类的错误，十有八九就是驱动没装对。

可以用下面这条命令快速看驱动状态：

ls /dev/dri/

如果输出里有card0和renderD128，说明显卡设备节点正常。再看一下系统里有没有加载对应的内核模块：

lsmod | grep -E "drm|mthreads|sgit"

如果什么都没有，建议先把驱动补齐再装 CAP，不然回头排查起来很纠结。

2.3 关闭系统安全限制和更新源

统信 UOS 这类系统默认可能开启了一些安全管控机制，比如命令执行限制、软件来源校验，它们有可能会拦截 CAP 安装过程中的脚本操作。我不建议你去关掉系统级的安全服务（尤其是公司统一管理的机器），但可以先把系统的开发者模式打开。以统信 UOS 为例：

1. 打开“控制中心” -> “通用” -> “开发者模式”。
2. 点击进入，按提示完成在线认证或离线激活。
3. 开启后系统会允许运行未经过商店签名校验的本地应用。

另外，安装前建议先更新一下系统软件源，减少依赖版本过旧导致的意外：

sudo apt update && sudo apt upgrade -y

注意这一步耗时取决于网络情况，统信 UOS 的源服务器有时候不稳定，耐心等就行。

3. 安装过程全记录：从下载到首次启动

3.1 获取安装包

芯语 CAP 有在线安装和离线包安装两种方式。我建议能联网的机器优先用在线安装，因为在线模式下它会自动校验依赖并下载对应版本的运行时；如果是内网隔离环境，那就用离线包。

假设你已经拿到了官方提供的安装包（通常是.tar.xz格式的压缩包，里面包含install.sh脚本），先解压：

tar -xf xinyu_cap_installer.tar.xz cd xinyu_cap_installer

3.2 执行安装脚本

官方推荐用普通用户配合 sudo 执行安装脚本，不建议直接 root 运行。原因有两个：一是脚本内部有些路径会动态读取当前用户的 HOME 目录，root 身份可能导致后续服务路径混乱；二是安全考虑，万一脚本有问题，普通用户身份至少能限制影响范围。

chmod +x install.sh sudo ./install.sh

安装过程大概持续 5~10 分钟，脚本会依次做这几件事：

1. 检查 CPU 架构和系统发行版；
2. 生成独立的运行目录，默认在/opt/xinyu-cap；
3. 把内置的 Python 运行时（自带的 3.10 版本）、Node.js 运行时、FFmpeg 等工具链解压到对应目录；
4. 配置 PATH 环境变量，并写入/etc/profile.d/xinyucap.sh；
5. 创建系统服务xinyu-cap.service，用于后台常驻组件；
6. 在桌面创建启动快捷方式。

我在安装过程中遇到过一个细节：脚本会检测当时是否有其他包管理进程在运行（比如apt或dpkg正在执行），如果有，它会暂停并提示你稍等片刻再重试。这个设计很人性化，避免了很多诡异的半安装状态。

3.3 启动与初始化

安装完成后先别急着用，做一次重启或重新加载环境变量：

source /etc/profile

然后启动服务：

sudo systemctl start xinyu-cap sudo systemctl status xinyu-cap

看到active (running)状态，说明后台服务起来了。这时桌面菜单里应该能看到“芯语 CAP”的图标，双击即可打开图形界面。

如果是无桌面环境（比如纯命令行服务器场景），可以直接通过命令行启动用户端：

xinyu-cap-cli

命令行终端下看到的是一个交互式面板，能用方向键和回车浏览应用列表，这种设计对服务器用户比较友好。

首次启动图形界面时，它会让你选择一个“数据存储路径”。这个路径用来存放下载的模型文件、应用配置和运行日志，默认是~/xinyu-cap-data，我建议你改到剩余空间比较大的分区。因为后续模型文件动辄几个 GB，放在系统盘容易把根目录塞满，到时候系统直接卡死，很被动。

3.4 验证安装是否成功

打开主界面后，你应该能看到一个应用市场页面，左侧是分类导航，右侧是应用卡片。如果这个页面正常出来，说明安装成功。再进一步验证一下运行环境：

xinyu-cap doctor

这个命令会做一个全面的自检，包括运行时版本、依赖库、硬件解码能力、网络连通性。我的实测输出大概是这样的：

[X] LoongArch 检测通过 [X] Python 运行时 3.10.15 (embedded) [X] FFmpeg 检测通过 [X] 磁盘空间充足 (剩余 128.6 GB) [X] GPU 设备检测通过 (whocan: 1024 MiB) [!] 建议：模型缓存路径剩余空间不足 50 GB，可考虑迁移

如果出现[X]开头的行，按提示处理即可；如果出现[!]，只是警告，不阻塞使用。

4. 核心功能实战：装一个真正的 AI 应用走完流程

安装成功只是开始，真正考验人的是装完应用之后能不能跑起来。我带大家完整走一遍我实际操作的经典案例——在芯语 CAP 里安装并运行一个本地大模型问答工具，同时穿插说明商店内各类应用的使用逻辑。

4.1 逛商店，选对你需要的应用类型

打开 CAP 主界面后，你会看到应用列表按类别整理，大致有以下几类：

新手建议从“对话助手”开始，一是应用逻辑简单，二是 CAP 对这类应用的封装做得最成熟，“一键安装”的成功率最高。

以我选的“本地问答助手参考应用”为例，它的卡片上会标明所需内存、磁盘空间、模型大小，以及一个明显的“安装”按钮。点下去之后注意看右上角的进度提示，它实际上会依次完成三件事：下载配好的预编译依赖包、拉取指定模型文件、生成启动配置。

4.2 第一次安装时发生了什么：深入拆解安装逻辑

我最初以为 CAP 只是做了一个 apt 式的软件包下载器，后来细看日志发现它的设计比我想象得巧妙：

1. 它先检查当前系统的 glibc 版本、内核版本，并和内置的“兼容性清单”比对。如果系统太老或太新，它会选择对应版本的 Wheel 包，而不是下载通用包。
2. 它内部维护了一个“Python 虚拟环境仓库”，每个应用安装时都会克隆一个基础环境，再叠加应用自身的依赖。这样做的好处是：应用 A 需要 numpy 2.0，应用 B 需要 numpy 1.24，两个应用互不干扰。
3. 模型文件采用了断点续传的下载机制，中途断网重连后能接着下载。

这个设计我在实际使用中感受很深。之前手动配置 AI 环境时，最头疼的就是“装好了这个库、又把那个库搞崩了”的连锁反应，CAP 的隔离方案算是从根上解决了这个问题。

4.3 启动应用，跑第一轮问答

安装完成后，应用卡片上的按钮会变成“启动”或“打开”。点击启动后，它会为这个应用拉起一个独立的运行进程，并自动在系统托盘中保持常驻。首次启动时由于需要加载模型到内存，等待时间会长一些，通常在 10~30 秒之间，这取决于你的磁盘读取速度和内存大小。

启动完成后会弹出一个对话窗口，类似 ChatGPT 的界面。我随便输入了一句“介绍一下龙芯处理器的特点”，它回复速度大约在每秒 15 个 token 左右，用的是 CPU 推理，在 3A6000 上表现属于中规中矩。如果你有算力卡，建议在应用的“设置”菜单里把推理设备从 CPU 切换为 GPU，速度会有非常明显的提升。

这里有一个值得注意的细节：部分模型在 CAP 里默认用了 4 bit 量化，所以显示效果和官方展示的 demo 可能有细微差异，这是正常现象。量化就是为了在资源有限的平台上跑起来，牺牲一点精度换取可用性，跑本地模型是完全合理的取舍。

4.4 更换或升级应用内模型

对话助手的默认模型不一定满足你的需求，比如你可能想换一个参数更大的模型，或者切换为垂直领域微调版本。在 CAP 中，这个操作也做了简化：

1. 进入应用的“模型管理”页面；
2. 浏览可下载模型列表，CAP 会标注每个模型的大小、所需内存、量化方式；
3. 点击下载，等进度条跑完；
4. 在“默认模型”下拉框里选择新下载的模型。

整个过程不需要你手动调整代码里的模型路径，CAP 会在后台统一管理模型文件的存储目录和调用链。我实际下载了一个 7B 级别的模型，文件大小约 4.7 GB，在普通千兆网络下大约十分钟拉完。下载完成后立即切换，没有出现需要重启才能生效的问题。

5. 我踩过的坑：CLI 命令、权限问题、下载中断排查

不管写多少篇指南，实际操作中总会冒出一些文档里没有的意外。这一部分我把自己反复踩过的坑都整理出来，给你当参考。这里面没有哪一条是“可能遇到”，全是“大概率遇到”。

5.1 应用启动时提示端口被占用

CAP 的一些应用（尤其是 Web 界面形式的工具）会默认监听本地端口，比如 8080、7860。如果你之前手动部署过其他服务，占用了这些端口，应用就会启动失败，并且只在日志里留下一行模糊提示。

排查方法：

ss -tlnp | grep 7860

找到占用进程后，有两种办法：要么关掉冲突进程，要么在 CAP 应用设置里修改端口号。大多数 CAP 应用在“参数配置”一栏提供了port这类可调参数，改成一个冷门端口比如 18100，应用重启后生效。

这里要提醒一点：端口设置别用 1~1023 的权限端口，否则普通用户没有绑定权限，启动会报 permission denied。我一开始不知道，把端口改成 80，结果每次都要 sudo 启动，后来改成 18080 就清净了。

5.2 模型下载到一半停了，重新安装也没用

这是我踩得最深的坑。有段时间下载一个大模型，进度停在 84%，重试好几次都从 0 开始。后来翻日志才发现，CAP 的模型下载默认放在~/xinyu-cap-data/models下，用临时文件存储下载进度，只要你不主动清理临时文件，理论上重启程序后应该能“断点续传”。但如果你在安装中强制结束过进程，或者手动删过临时目录内容，就会导致进度丢失。

我的建议是：

1. 优先确认下载目标是官方源还是镜像源；内网环境特别容易出现下载到一半连接被重置的问题。
2. 如果多次失败，手动把模型下载地址复制到浏览器或下载工具里，先下载到本地，再通过“模型管理”页面的“从本地导入”功能上传。虽然是笨办法，但胜在稳定。

5.3 找不到卸载命令，或者卸载不干净

你可能装了后悔想卸载，或者装完发现版本不对需要重装。CAP 提供了卸载脚本，但在安装目录里，不是系统 PATH 里：

sudo /opt/xinyu-cap/uninstall.sh

卸载过程会停止系统服务、删除应用目录，但有一个地方它默认不会清理——用户数据目录（模型、配置、下载记录）。这样设计是合理的，防止你误删已下载的大文件，但对强迫症来说不够彻底。手动清理：

rm -rf ~/xinyu-cap-data

另外注意：某些应用的虚拟环境在卸载后可能残留于/opt/xinyu-cap/apps下，如果确认不再使用，可以一并清理，腾出不少空间。

5.4 命令行终端和桌面图标进入的是完全不同的两个实例

这个坑非常隐蔽。我有一次从命令行启动xinyu-cap-cli，在里面安装了一个应用，回到桌面打开图形界面的时候，那个应用居然显示“未安装”。查了文档才知道：CLI 和 GUI 默认的连接配置不同，CLI 使用的是~/.xinyu-cap/config.json里的独立存储路径，而 GUI 使用的是系统级配置。

解决办法很简单，确认使用同一个数据目录：

xinyu-cap config set>xinyu-cap repo download-app <应用名> --output-dir /data/cap-offline-repo

再把/data/cap-offline-repo整个目录拷贝到内网机器上，然后在目标机器上执行：

xinyu-cap repo import-local --dir /data/cap-offline-repo

这样就不需要每一台机器单独去外网下载东西。更重要的是，模型文件也支持离线导入方式，我上面其实提过一句，这里展开说一下操作路径：图形界面里的“模型管理”页面下方，有一个“从本机文件夹导入”的按钮，选择你预先下载好的模型文件（通常是 GGUF 格式），它会自动做校验和注册，不需要你手工修改任何配置文件。这样，在一个完全没有外网的环境下，也能完整使用大模型应用。这招尤其适合那种只能通过光盘/U盘摆渡文件的涉密或管控网络场景。

6.2 给普通用户最小权限，批量分发

如果你负责给团队十台八台机器部署 CAP，不建议每台都用你的管理员账号操作。可以这样做：

• 安装时用管理员账户完成；
• 然后修改数据目录的属主，把已配置好的环境和模型让普通用户使用：

sudo chown -R 用户名:用户名 /home/用户名/xinyu-cap-data sudo chmod -R 755 /home/用户名/xinyu-cap-data

之后普通用户打开桌面图标，能正常启动 CAP，也能运行已装好的应用，但没法自行安装新应用（需要管理员权限的操作会被系统拦下）。这既保证了灵活性，又不至于让团队里的每个人都能乱装东西。

6.3 应用程序数据备份与恢复

模型文件重新下载很费时间，所以定期备份数据目录是个好习惯。最轻量的做法是把数据盘直接复制到移动硬盘：

rsync -av --progress ~/xinyu-cap-data/ /mnt/usb/cap-backup/

恢复时再反向执行一次即可。需要注意，备份前最好先把 CAP 退出，避免有文件正在写入导致备份不完整。

我个人的习惯是每周五下班前跑一次增量备份，因为新下的模型、改过的配置都能及时捞回来，一旦系统盘挂了，不至于一切重来。群里有个朋友就吃过亏——系统崩溃重装后，几百 GB 的模型全没了，重新下载花了两天。

6.4 把 CAP 应用能力集成到自己的工作流

这是一个容易被忽略的进阶用法：CAP 安装的应用，其底层 API 和命令行工具其实是暴露给用户的。比如你安装了 OCR 应用，那你完全可以直接在 shell 脚本里调用它的 OCR 功能：

xinyu-cap run app-ocr --image /path/to/photo.png

它会返回识别出的文本结果。这意味着你可以把 CAP 里的 AI 工具当作“组件”来组装自己的自动化流程，比如写个 Shell 脚本批量识别扫描件里的发票号，再自动归档到表格里，整个过程完全不打开图形界面，效率和体验感完全是两个级别。

我刚发现这个能力的时候有一种“彩票刮出奖”的感觉——本来以为只能点图标用用，后来发现它保留了底层接口，对个人用户来说这相当于白送了一套 AI 工具库。

7. 最后分享一个实打实的体会

我从拿到龙芯主机、到摸索装 AI 工具、再到现在把 CAP 当作日常生产力工具，整个过程最大的感受是：龙芯平台真正缺的不是硬件性能，而是“让人能轻松用起来”的软件生态。芯片再强，普通用户装个软件都费劲，那一切性能都白搭。

芯语 CAP 这类工具的出现，本质上是在帮整个生态补最短的那块木板。虽然它现在还做不到像成熟商业应用商店那样应用数量庞大，但“把复杂环境封装好、让安装变成点击一下”这个思路，方向完全正确。我相信随着龙芯平台用户增多，仓库里的应用会越来越丰富，那时候回头看你今天踩过的这些安装坑，会觉得非常值得。

如果你也是龙芯用户，正在为装 AI 工具发愁，这篇文章里的步骤可以直接当成操作手册来用。装好了之后，多去逛逛应用商店里的“推荐”和“新上架”栏目，时不时会有惊喜。祝你在龙芯平台上玩得开心。