安装指南

CSGLite 提供多种安装方式，支持跨平台运行。

系统要求与前提条件

操作系统: macOS (Apple Silicon / Intel)、Linux (x86_64 / ARM64)、Windows (x86_64)
推理依赖: llama-server（模型推理必需，安装脚本会自动尝试安装）
编译依赖: Go 1.22+（仅从源码编译时需要）

方式一：一键安装脚本（推荐）

适用于 Linux 和 macOS，自动检测系统架构，从 GitHub Releases 下载安装。

curl -fsSL https://hub.opencsg.com/csghub-lite/install.sh | sh

在 macOS 上，安装脚本会优先选择当前已经在 PATH 且可写的目录（例如 /opt/homebrew/bin），找不到时再回退到 ~/bin，尽量避免使用 sudo。如果回退到了 ~/bin，脚本会自动写入 shell 配置，并提示当前终端立刻生效的命令。

指定版本安装

curl -fsSL https://hub.opencsg.com/csghub-lite/install.sh | CSGHUB_LITE_VERSION=v0.8.55 sh

企业版安装（会额外把 `license.txt` 写入安装目录）

curl -fsSL https://hub.opencsg.com/csghub-lite/install.sh | EE=1 sh

Windows (PowerShell) 一键安装

在 PowerShell 中运行以下命令：

$env:EE="1"; irm https://hub.opencsg.com/csghub-lite/install.ps1 | iex

安装脚本环境变量（可选）

install.sh 与 install.ps1 共同支持以下通用变量，用于自定义安装行为：

变量	说明
`EE`	设为 `1` 时，将企业版 `license.txt` 写入 `csghub-lite` 安装目录。
`INSTALL_DIR`	指定 `csghub-lite` 安装目录。未设置时，macOS 优先选择 `PATH` 中可写的目录，否则回退到 `~/bin`；Linux 默认使用已有安装目录或 `/usr/local/bin`。
`CSGHUB_LITE_LLAMA_SERVER_INSTALL_DIR`	指定 `llama-server` 安装目录。未设置时，macOS 默认跟随 `csghub-lite` 的安装目录。
`CSGHUB_LITE_LLAMA_CPP_TAG`	指定要安装的 `llama.cpp` release tag。默认固定到与内置 `convert_hf_to_gguf.py` / `gguf-py` 对齐的 tag，确保版本一致。
`CSGHUB_LITE_AUTO_INSTALL_LLAMA_SERVER`	设为 `0` 可跳过自动安装/升级 `llama-server`。
`CSGHUB_LITE_AUTO_INSTALL_PATCHELF`	Linux 上设为 `0` 可禁止自动 `apt/dnf/yum install patchelf`（用于为 `llama-server` 设置 `$ORIGIN`，使同目录 `.so` 可被直接加载）。
`CSGHUB_LITE_LLAMA_ROCM_VERSION`	Linux 上可显式指定优先尝试的 ROCm 资产版本（例如 `7.2`）。未设置时，安装脚本会尝试从本机 ROCm 环境自动识别版本，再回退到发布页中可用的其他 ROCm/Vulkan/CPU 包。

说明：若远程 llama.cpp 与本地 build 号一致，脚本会跳过重新下载；此前若因缺少依赖导致 llama-server --version 失败，会被误判为需要升级——新版本已使用 LD_LIBRARY_PATH 检测版本，并从压缩包中递归安装所有需要的 .so 文件。

方式二：Homebrew（主要面向 macOS）

作为 macOS 用户的可选额外入口，运行以下命令安装：

brew tap opencsgs/csghub-lite https://github.com/OpenCSGs/csghub-lite
brew install opencsgs/csghub-lite/csghub-lite

方式三：GitHub Releases 手动下载

前往 Releases 页面，根据您的平台下载对应的压缩包：

平台	文件名
macOS Apple Silicon	`csghub-lite_*_darwin_arm64.tar.gz`
macOS Intel	`csghub-lite_*_darwin_amd64.tar.gz`
Linux x86_64	`csghub-lite_*_linux_amd64.tar.gz`
Linux ARM64	`csghub-lite_*_linux_arm64.tar.gz`
Windows x86_64	`csghub-lite_*_windows_amd64.zip`

下载后解压并移动到一个已经在 PATH 中的目录，例如 ~/bin、/opt/homebrew/bin 或 /usr/local/bin：

tar xzf csghub-lite_*.tar.gz
mkdir -p "$HOME/bin"
mv csghub-lite "$HOME/bin/"

方式四：Linux 包管理器

Debian / Ubuntu 平台

sudo dpkg -i csghub-lite_*.deb

RHEL / CentOS / Fedora 平台

sudo rpm -i csghub-lite_*.rpm

方式五：从源码编译

git clone https://github.com/opencsgs/csghub-lite.git
cd csghub-lite
make build
# 编译后的二进制文件位于 bin/csghub-lite

若需进行全平台编译，可以运行：

make build-all

安装推理后端 (llama-server)

csghub-lite 使用 llama.cpp 的 llama-server 进行本地模型推理。如果您是手动编译或未使用一键安装脚本，请确保单独安装了它：

macOS

brew install llama.cpp

Linux / Windows

从 llama.cpp Releases 下载对应平台的预编译包，解压后将 llama-server 放入 PATH 即可。

# 示例：Linux x86_64
wget https://github.com/ggml-org/llama.cpp/releases/download/b9158/llama-b9158-bin-ubuntu-x64.tar.gz
tar xzf llama-b9158-bin-ubuntu-x64.tar.gz
sudo cp build/bin/llama-server /usr/local/bin/

验证安装

csghub-lite --version
llama-server --version

使用 Docker 运行 (Docker 运行镜像)

CSGLite 提供了官方 Docker 容器镜像。它们是轻量级的引导运行时，内置了运行所需的 OS 和 GPU 依赖。在容器启动时，它们会根据环境变量自动下载 csghub-lite 和匹配的 llama-server。

[!IMPORTANT] 请务必将主机目录挂载到容器的 /root/.csghub-lite 路径。这样可以保证下载的二进制文件、模型、引擎、配置和 Token 在容器重启或重建后得以持久保存。

官方镜像列表

镜像名称	适用场景
`opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latest`	标准 Linux CPU/GPU 运行时
`opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite-rocm:latest`	适配 AMD GPU 的 ROCm 运行时

容器安装策略与配置变量

环境变量	说明
`CSGHUB_LITE_VERSION`	锁定 csghub-lite 的版本，例如 `v0.8.55`。
`CSGHUB_LITE_LLAMA_CPP_TAG`	锁定 llama.cpp 推理引擎的版本，例如 `b9158`。
`CSGHUB_LITE_INSTALL_POLICY`	安装策略，可选：`if-missing`（默认，不存在则下载）、`if-version-mismatch`（版本不一致时下载）、或 `always`（每次启动都重新下载）。
`CSGHUB_LITE_INSTALL_ALWAYS`	设为 `1` 时强制在每次启动时重新下载/覆盖安装。
`CSGHUB_LITE_INSTALL_URL`	自定义下载源地址（适用于私有部署镜像源）。
`CSGHUB_LITE_REGION`	下载地区，例如 `CN` 或 `INTL`。
`CSGHUB_LITE_REQUIRE_LLAMA_SERVER`	设为 `0` 可在容器内关闭本地 `llama-server` 的安装（仅使用云端 API 推理）。

运行示例

1. 标准运行时部署

# 创建持久化目录
mkdir -p ~/.csghub-lite-docker

# 启动容器并挂载卷
docker run -d --name csghub-lite \
  -p 11435:11435 \
  -v ~/.csghub-lite-docker:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latest

2. 版本锁定与更新策略

docker run -d --name csghub-lite \
  -p 11435:11435 \
  -e CSGHUB_LITE_VERSION=v0.8.55 \
  -e CSGHUB_LITE_LLAMA_CPP_TAG=b9158 \
  -e CSGHUB_LITE_INSTALL_POLICY=if-version-mismatch \
  -v csghub-lite-data:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latest

3. 强制在容器启动时升级

docker run -d --name csghub-lite \
  -p 11435:11435 \
  -e CSGHUB_LITE_INSTALL_ALWAYS=1 \
  -v csghub-lite-data:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latest

4. 适配 AMD GPU 的 ROCm 部署

docker run -d --name csghub-lite-rocm \
  --device=/dev/kfd \
  --device=/dev/dri \
  --group-add video \
  --ipc=host \
  --security-opt seccomp=unconfined \
  -p 11435:11435 \
  -e CSGHUB_LITE_VERSION=v0.8.52 \
  -v csghub-lite-data:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite-rocm:latest

提示：csghub-lite-rocm 镜像内置了 SafeTensors 转 GGUF 的 Python 转换环境（包含 PyTorch, safetensors, transformers 和 sentencepiece）。首次启动时，如果挂载目录中没有该环境，容器会自动将其写入 /root/.csghub-lite/tools/python。

系统要求与前提条件​

方式一：一键安装脚本（推荐）​

指定版本安装​

企业版安装（会额外把 license.txt 写入安装目录）​

Windows (PowerShell) 一键安装​

安装脚本环境变量（可选）​

方式二：Homebrew（主要面向 macOS）​

方式三：GitHub Releases 手动下载​

方式四：Linux 包管理器​

Debian / Ubuntu 平台​

RHEL / CentOS / Fedora 平台​

方式五：从源码编译​

安装推理后端 (llama-server)​

macOS​

Linux / Windows​

验证安装​

使用 Docker 运行 (Docker 运行镜像)​

官方镜像列表​

容器安装策略与配置变量​

运行示例​

1. 标准运行时部署​

2. 版本锁定与更新策略​

3. 强制在容器启动时升级​

4. 适配 AMD GPU 的 ROCm 部署​