常见问题

运行它需要什么？

一台装有 Python 3.11 或更新版本的机器，基本就这样。macOS arm64、Linux amd64 和 Windows amd64 都由同一个纯 Python 发行版覆盖，不需要 GPU。只有拉流和监听模式的视频源（RTSP、RTMP、SRT）需要系统里的 ffmpeg；网络摄像头、文件或浏览器界面都不需要。

安装脚本把东西放在哪里？

两个地方。~/.cardstream 是安装根目录：venv/ 里是虚拟环境，models/ 里是模型权重。两个命令 cardstream-web 和 cardstream-client 是写入 ~/.local/bin 的小型启动脚本，它们以预先填好模型路径的方式执行虚拟环境里的程序，所以你传入的任何参数都会优先生效。两个位置都可以用 CARDSTREAM_HOME 和 INSTALL_DIR 改变。机器上的其他地方一概不碰，尤其是脚本绝不会编辑你的 shell 配置文件：如果 ~/.local/bin 不在你的 PATH 里，它只会打印一条提示，把改动留给你自己。

如何更新到新版本？

再跑一次同样的那行命令。它会把当前发行版装进已有的虚拟环境并重写启动脚本。已经在 ~/.cardstream/models 里的权重不会被动（权重只在缺失时才下载），所以一次更新只是很小的下载量，而不是再来四分之一 GB。想装某个特定版本而不是最新版，设置 CARDSTREAM_VERSION 即可。

# 同一行命令；/install.sh 会重定向到 main 分支上的脚本
$ curl -fsSL https://cardstream.ai/install.sh | sh
$ curl -fsSL https://cardstream.ai/install.sh | CARDSTREAM_VERSION=v0.5.0 sh
$ cardstream-web --version

如何卸载？

两条命令。第一条删除虚拟环境和模型权重，第二条删除两个启动脚本。没有别的要清理的了：没有守护进程，没有登录项，没有系统软件包。

$ rm -rf ~/.cardstream # venv/ + models/
$ rm -f ~/.local/bin/cardstream-web ~/.local/bin/cardstream-client

如果安装时设置了 CARDSTREAM_HOME 或 INSTALL_DIR，请改为删除那些路径；如果把启动脚本放进了系统目录，需要用 sudo。你手动添加的东西仍需自己撤销：shell 配置文件里的 PATH 行、XIMILAR_API_KEY 的 export，以及传给 --store-images 的任何文件夹。除此之外，应用不会在你的主目录下写任何其他东西。在一个新开的 shell 里运行 command -v cardstream-web 确认它已消失；旧的 shell 会缓存查找结果，直到你运行 hash -r。

需要 GPU 吗？

不需要。随包附带的权重是为 CPU 准备的 ONNX 导出，本地引擎做的一切（运动闸门、检测节流、回答"同一张卡还是新卡？"的嵌入模型）都在你手头的处理器上运行。GPU 是你用自己的高精度权重时的一个选项，默认配置绝不需要它。

能配合 Whatnot 或 Fanatics Live 使用吗？

可以，但不是接入交易平台，而是接入你已经在制作的视频。OBS 虚拟摄像头、在推给平台那一路旁边再加一路 RTMP 或 SRT 输出、从编码器拉 RTSP，或者干脆用一台自己的摄像头对准同一块桌面。直播卖家指南把这四条路线从头到尾走了一遍。

到底有什么会离开我的机器？

在客户端模式下，每张不同的卡只发一张 JPEG 裁切图：不是视频流，不是前后的帧，也不是桌面的其他部分。要不要发送的每一个决定都先在本地做出，所以一小时里展示了一百张卡的视频，就是一百个小请求。唯一的例外由你自己决定是否开启：使用 --ximilar-stream 时，这场直播的历史记录（每张卡一行文本，外加据以识别它的那张裁切图）也会保存到你自己 Ximilar 账号里的一个会话中。默认关闭，而 --no-ximilar-stream-images 可以让它只保存文本。

直播结束后还能回看吗？

可以，前提是你保存了它。用 --ximilar-stream NEW 启动，历史记录列出的每张卡（连同价格、在直播中停留的时长和据以识别它的裁切图）都会在直播进行时发送到你 Ximilar 账号里的一个会话。事后打开 Ximilar 应用的 Cardstream 板块：这场直播的总价值、最有价值的商品和热门系列、每张卡及其图片；还可以标记已售出的卡、更正认错的匹配。直播中途重启了？把 NEW 换成会话 id，它就会接着进行，即使会话已经关闭也一样。要保存到团队工作区，用 --ximilar-workspace。详细说明。

$ cardstream-web --price-stats --ximilar-stream NEW

能在局域网里运行，让另一台机器打开界面吗？

别这样做。Web 界面没有身份验证，并且持有你的 API 密钥，所以它只应该待在 127.0.0.1 上。容器内部绑定的是 0.0.0.0，正因如此，文档里的 docker run 才只把端口发布到 127.0.0.1。如果确实需要从另一台机器访问，请在前面架一条你自己的带身份验证的隧道，而不是打开端口。

$ docker run --rm -e XIMILAR_API_KEY -p 127.0.0.1:8001:8001 \
    -v cardstream-models:/models cardstream