下载

让 cardstream 跑起来

macOS 和 Linux 上一条命令搞定；想要更多控制时，有发行版 wheel、Dockerfile 和源码构建。macOS arm64、Linux amd64 和 Windows amd64 都由同一个纯 Python 发行版覆盖。

安装脚本

一条命令完成安装

在 ~/.cardstream 里创建虚拟环境，用校验和验证发行版 wheel，下载模型权重，并把 cardstream-web 和 cardstream-client 加到 PATH。如果装了 uv，会优先使用。

$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh
$ export XIMILAR_API_KEY=your-key
$ cardstream-web
# → http://127.0.0.1:8001 — 把卡举到镜头前

需要时可用的选项

CARDSTREAM_VERSION — 固定到某个发行版标签而不是最新版，例如 v0.5.0
CARDSTREAM_HOME — 存放虚拟环境和模型的安装根目录（默认 ~/.cardstream）
INSTALL_DIR — cardstream-web / cardstream-client 启动脚本的存放位置（默认 ~/.local/bin）
CARDSTREAM_MODELS_BASE_URL — 各模型权重 tarball 的备用下载地址
CARDSTREAM_MODEL_ARCHIVES — 从那里下载哪些 tarball（空格分隔）
CARDSTREAM_EXTRAS — 要安装的 pip extras（默认 client,onnx）
CARDSTREAM_TRACKER_URL — 可选的 vitTracker .onnx（默认：OpenCV zoo）

验证

验证安装

脚本在安装任何东西之前，会先用发行版的 SHA256SUMS 验证 wheel。装好后，一个参数就能确认机器上装的是什么：

$ cardstream-web --version
cardstream 0.5.0

自己下载的构建产物？用脚本同样的方法检查：shasum -a 256 -c SHA256SUMS。

手动下载

直接从发行版获取

包发布在 PyPI，每个 GitHub 发行版里也带有同一个 wheel 和 sdist，旁边是 SHA256SUMS。一个纯 Python 的 wheel 覆盖所有平台：

$ pip install 'cardstream[client,onnx]'

Windows

安装脚本只支持 POSIX；在 Windows 上请从 PyPI 安装，从模型发行版解压各模型的权重 tarball，再用参数指向它们：

> py -3.11 -m venv cardstream-env
> cardstream-env\Scripts\activate
> pip install 'cardstream[client,onnx]'
> set XIMILAR_API_KEY=your-key
> cardstream-web --segmentor-model models\segmentation_model\onnx\model.onnx ^
    --embed-model models\similarity_model\onnx\model.onnx

对比

选择方式

方式	适合	首次验证
安装脚本	想在 localhost 上最快跑起来：虚拟环境、模型权重和 PATH 启动脚本全帮你搞定。	`cardstream-web --version`
Docker	干净的主机，或者在编码器附近的机器上接收 OBS 推流。	`curl -s http://127.0.0.1:8001/mode`
从源码构建	你要改代码。	`pytest -q tests/core/test_engine.py`

Docker

在容器里运行

镜像首次启动时会把模型权重下载到一个卷里，然后启动 Web 客户端。用仓库里的 Dockerfile 构建：

$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream
$ docker build -t cardstream .
$ docker run --rm -e XIMILAR_API_KEY -p 127.0.0.1:8001:8001 \
    -v cardstream-models:/models cardstream

容器内部绑定在 0.0.0.0，所以请像上面那样只把端口发布到 127.0.0.1。这个应用没有身份验证，并且持有你的 Ximilar API 密钥；绝不要把它暴露到局域网或互联网。

源码

从源码构建

检出仓库，跑一个脚本，再用离线测试套件做首次验证。加上 --models 还会顺带下载权重。

$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream
$ ./scripts/build-from-source.sh --models
$ source .venv/bin/activate
$ cardstream-web --version

下一步

安装与运行 →

你的密钥、首次运行，以及要检查什么。

把你的直播喂给它 →

网络摄像头、RTSP 拉流、OBS 直接推流。

放心运行 →

阈值、推荐配置，以及如何只留在 localhost。

更新或卸载 →

脚本把东西放在哪里，以及撤销它的两条命令。