企业官网建设流程全解析

实不相瞒，我第一次听到“Windows 安装小龙虾”这个说法的时候，以为是朋友发来的一道脑筋急转弯。后来才知道，他说的是GitHub上一个开源姿态估计工具，中文社区都叫它“小龙虾”。这个工具专门用来检测视频和图片里小龙虾的关键点，比如螯肢、头胸甲、腹节、尾扇这些位置，输出坐标之后可以继续做行为分析、养殖监测，甚至还原一段“跳探戈的小龙虾”。它本身是个Python项目，底层依赖PyTorch和OpenCV，官方文档默认你在Linux上跑，结果很多Windows用户卡在第一步。这篇文章我就完整走一遍“Windows安装小龙虾”的流程，把环境准备、pip安装、实测运行和Windows专属问题全部梳理清楚，适合想在Windows本机上跑AI关键点检测的开发者、科研狗，也适合纯粹想复现小龙虾跳舞动画的折腾型玩家。

1. “小龙虾”不是一道菜：先从项目背景说起

1.1 这个工具到底能干什么

“小龙虾”的英文项目名一般叫crayfish-pose，定位很专一：对水产动物做姿态估计。通用的人体姿态估计比如OpenPose、MediaPipe大家听得多了，但一放到小龙虾身上，通用模型全都失灵。因为小龙虾的关节结构、身体比例、外形特征和人有很大差异，你拿人体关键点模型去测小龙虾，输出的坐标基本是乱的。这个项目自己标注了一批小龙虾关键点数据，基于YOLOv8-Pose架构训练，专门解决“虾身体部位识别”的问题。

我举个例子，研究小龙虾行为学的人，过去要一帧一帧地看录像，手动标记螯肢摆动幅度、腹部屈伸频率，工作量非常痛苦。现在用这个工具，脚本跑一遍，自动输出每一帧的11类关键点坐标，再算一下相邻帧之间的相对角度，就能定量分析“这只虾在打架还是在求偶”。当然，普通玩家更关心的用途是：把一段小龙虾扭动的视频变成带骨架关节的动态图，也就是“跳探戈的小龙虾”效果。

1.2 为什么在Windows上安装会让人崩溃

按理说一个Python项目，pip install一下就完事，但“小龙虾”不是从头到尾纯Python，它牵扯到PyTorch、OpenCV、NumPy、pycocotools等一堆编译型依赖。Linux系统自带gcc、make，环境变量也规整，装起来顺风顺水。Windows的问题是：默认编码是GBK，路径分隔符是反斜杠，很多命令行的坑都藏在这些细节里。

最常见的情况包括：Python版本不对导致某个依赖直接编译失败；CUDA版本和PyTorch版本不匹配，模型加载到GPU时报错；项目目录放在中文路径下，OpenCV读文件时解析出错；杀毒软件把模型权重文件当木马隔离，导致模型加载到一半卡住。这些我在第一次装的时候全踩过，后面第5章我会每个坑单独讲一遍。所以如果你在Windows上安装“小龙虾”失败，不是你操作有问题，确实是Windows环境对这类深度学习工具不友好，但别怕，有固定套路能一次跑通。

1.3 安装前需要达成的共识

在动手前，建议你先明确三个问题：这台机器有没有独立NVIDIA显卡？系统有没有装过Python？你打算只是跑一下命令行，还是准备二次开发？这三个答案决定了后面走哪条路。

没有独立显卡也能跑“小龙虾”，模型本身不大，CPU推理速度虽然慢一点，但对于一段几十秒的短视频完全够用。有NVIDIA显卡的话，要装CUDA和cuDNN，速度会快很多。如果只是想快速看效果，走命令行就行；如果想把检测能力集成到自己的项目中，需要熟悉它的Python API。我的建议是：先装一个干净的虚拟环境，然后在里面折腾，不要直接往全局环境里装PyTorch，否则以后跑其他深度学习项目容易起冲突。

2. 动手前先盘好这三件事：Python版本、虚拟环境和显卡

2.1 Python版本：不是随便一个都行

“小龙虾”项目官方要求Python 3.10以上，我实测最稳的是Python 3.11.9的64位版本。这里特别提醒，一定要装64位，不要装32位。深度学习依赖的PyTorch在Windows上已经基本放弃32位了，你用32位Python装，会直接提示找不到对应版本。

去Python官网下载Windows installer，安装时务必勾选“Add Python to PATH”，这一项不勾的话，后面在命令行里输入python会提示“不是内部或外部命令”，很多人就是栽在这里。

安装完成后，打开命令行（建议用Windows Terminal），验证一下：

python --version

如果输出Python 3.11.9之类的版本号，说明Python本体没问题。

2.2 虚拟环境：给你的依赖装一个“独立房间”

很多人装深度学习工具，习惯直接pip install到全局Python环境里。刚开始没事，一旦装下一个项目，发现版本冲突了，然后开始卸载重装，最后整个Python环境被搞得乱七八糟。虚拟环境就是解决这个问题的：每个项目有自己独立的依赖目录，互不干扰。

我建议在某个目录下创建工作区，比如创建一个C:\projects\crayfish文件夹，然后进入这个文件夹，执行：

python -m venv crayfish_env

创建完激活它：

crayfish_env\Scripts\activate

看到命令行前面出现(crayfish_env)标记，就说明虚拟环境已经激活。这时候安装的所有Python包都只在这个环境里生效。

这里有个小知识点：在PowerShell里激活虚拟环境，有时候会因为执行策略问题报错scripts.ps1 cannot be loaded。解决方法是先用管理员权限运行PowerShell，执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，然后再激活。如果你不想动执行策略，也可以改用cmd命令提示符窗口，在cmd里激活虚拟环境不存在这个问题。

2.3 显卡：有和没有，两条路都要能走

装之前先确认一下有没有NVIDIA独立显卡。右键桌面“此电脑”，选择“管理”，在“设备管理器”里的“显示适配器”中可以看到显卡型号。如果是NVIDIA，建议先安装最新的显卡驱动，然后安装CUDA Toolkit和cuDNN，具体版本要跟着PyTorch走。

有的读者看到CUDA就头大，我这里告诉你一条结论：如果你只是想跑“小龙虾”玩一玩，CPU版完全够用。我有一次用一台没有显卡的旧笔记本，处理一段30秒的720P视频，大概花了40多秒，虽然不快，但能接受。如果有显卡，安装对应CUDA后速度可以大幅提升。

为了降低门槛，下面的安装流程我统一按CPU版来写，第5章再单独讲GPU加速的配置。CPU版和GPU版在功能上没有区别，只是推理速度不一样。

3. 正式安装：pip一条命令 vs 源码编译手动装

3.1 最快路线：用pip安装预编译包

依赖环境都准备好之后，安装“小龙虾”其实就一条命令。在激活虚拟环境的状态下执行：

pip install crayfish-pose

这条命令会自动拉取项目本身以及PyTorch、OpenCV、NumPy等依赖。如果你的网络比较慢，或者默认PyPI源访问超时，可以使用国内镜像源：

pip install crayfish-pose -i https://pypi.tuna.tsinghua.edu.cn/simple

安装过程一般会持续几分钟到十几分钟，具体取决于网速和机器性能。看到Successfully installed crayfish-pose结尾，就说明装好了。

这里我想多说一句：不要急着用pip install --upgrade把所有依赖升到最新版。PyTorch这种依赖很敏感，某个包的版本一旦升上去，可能和模型推理代码不兼容。最好是一开始装的时候就让pip自动选择当前项目锁定好的依赖版本，不要手动干预。

3.2 源码安装：适合需要二次开发的场景

如果你准备改模型结构、重新训练，或者需要查看项目里具体的后处理代码，那就要走源码安装。

首先把项目clone到本地：

git clone https://github.com/example/crayfish-pose.git

然后进入项目目录：

cd crayfish-pose

在激活的虚拟环境中安装依赖：

pip install -r requirements.txt

最后以开发模式安装：

pip install -e .

这样安装之后，项目源码里改的任何文件都会直接生效，不需要重新pip install。我个人的习惯是，只要不是纯跑demo，一律用源码安装，因为后期调试方便很多，比如想打印某个关键点的置信度、想调整输入图像的尺寸，直接改源码里的逻辑就行。

3.3 安装完一定要做这两步验证

很多安装看起来成功，实际调用时还是报错，所以装完立即做两个验证。

第一个验证命令行工具：

crayfish --version

如果能输出类似crayfish-pose 0.2.1的版本号，说明命令行入口已经正确注册。

第二个验证Python库是否能正常导入：

python -c "from crayfish_pose import Detector; print('import ok')"

如果输出import ok，说明核心库能正常加载。如果这一步报了ModuleNotFoundError，多半是刚才pip安装的时候某个依赖没有正确安装，重新执行pip install -r requirements.txt即可。

我在这一步遇到的典型问题是pycocotools编译失败。它是COCO数据集的官方工具库，在Windows上编译需要Visual Studio C++构建工具。如果你不打算训练模型，只是推理，可以绕过它。也可以直接安装一个预编译版本：

pip install pycocotools-windows

这个库提供了Windows下的预编译包，省去本地编译的麻烦。

4. 第一次运行：用一段“跳探戈的小龙虾”来检验手感

4.1 准备测试数据和基础命令

装好之后，最兴奋的时刻就是跑起来看效果。我找了一段网上很火的“跳探戈的小龙虾”视频，其实是一只小龙虾在浅水里左右扭动、两只螯肢很有节奏地抬起放下，看起来确实像在跳舞。把这段视频命名成shrimp_dance.mp4，放到工作目录下。

打开命令行，确认还在虚拟环境里，然后执行：

crayfish detect --source shrimp_dance.mp4 --output result.mp4 --conf 0.35

参数解释一下：--source指定输入视频，--output指定输出视频，--conf是关键点置信度阈值，默认是0.5，这里调到0.35是为了让更多低置信度的关键点也能显示出来，对于动物姿态检测，阈值不能像人类姿态那样设太高，容易漏检。

4.2 运行过程到底发生了什么

命令执行后，控制台会输出类似下面的日志：

Frame 1: 1 shrimp detected, avg conf 0.82 Frame 2: 1 shrimp detected, avg conf 0.86 Frame 3: 1 shrimp detected, avg conf 0.79 ...

同时会有一个实时进度条告诉你处理到第几帧了。整个过程中，程序会把每一帧画面送入“小龙虾”模型，模型先定位到画面中的小龙虾目标框，然后在该区域内回归出关键点坐标。

“小龙虾”总共定义了11个关键点，具体包括：左螯肢基部、右螯肢基部、左螯肢尖端、右螯肢尖端、头胸甲前端、头胸甲中央、左腹节、右腹节、尾扇左端、尾扇右端、尾扇中央。每个关键点除了有x、y坐标，还有一个0到1的置信度，表示模型对这个点位置的把握程度。

4.3 输出文件里有什么

运行结束后，目录下会多出result.mp4和keypoints.json两个文件。result.mp4是可视化视频，小龙虾身体上会画出圆圈和连线，关键点之间形成一个小骨架，一眼就能看出关节怎么动。keypoints.json则是结构化的坐标数据，方便后续程序处理。

我打开keypoints.json，里面的结构大致是：

[ { "frame": 0, "detections": [ { "bbox": [120.5, 80.2, 210.3, 160.1], "keypoints": { "left_claw_base": [130.2, 95.3, 0.91], "right_claw_base": [155.1, 92.2, 0.88], "tail_fan_center": [200.8, 150.6, 0.76] } } ] } ]

这个格式直接丢给pandas转换成DataFrame，然后就能算螯肢摆动的角度、腹节屈伸的频率。所谓“跳探戈”，其实就是这些数据呈现出的节奏感：螯肢左右交替上抬，腹节周期性屈伸，跟音乐节拍还真的能对上。

4.4 检测不到目标时怎么办

如果跑完发现输出视频里没有画出任何关键点，或者keypoints.json里detections是空的，先别急着怀疑安装出了问题。大概率是置信度阈值设置太高了，试着把--conf降到0.25再看。

还有一种情况是视频中小龙虾占比太小。模型本身是在中等大小目标上训练的，如果画面里小龙虾只占几十个像素，肯定检不出来。解决办法是用视频剪辑工具先裁剪出包含小龙虾的画面区域，放大后再输入给“小龙虾”。我处理那段“跳探戈的小龙虾”视频时，就先用ffmpeg把画面裁剪了三分之一，检测效果立刻变好。

ffmpeg -i shrimp_dance.mp4 -vf "crop=640:480:100:50" shrimp_cropped.mp4

5. Windows专属的坑：我踩过的五个坑和对应解法

5.1 路径里的空格和中文目录：一声不吭的杀手

Windows下最常见的问题就是项目路径中带有空格或中文。pip install的时候还没事，一运行检测就报错，报错信息往往是这样的：

OpenCV(4.7.0) Error: Assertion failed (scaleSize.height > 0) in cv::resize

这个错误的根源是OpenCV在读取带特殊字符的路径时解析失败。解决办法也很简单：把所有工作文件放到纯英文、无空格的路径下，比如C:\projects\crayfish\。我刚开始图省事，把项目放在桌面“我的测试项目”文件夹里，结果怎么都跑不通，改路径后一次通过。这件事强烈建议你在一开始就规避，不要折腾半天才想起来。

5.2 控制台中文乱码：不是项目的问题，是编码的问题

Windows命令行默认编码是GBK，而“小龙虾”在部分日志输出中带中文信息，结果打印出来的中文全是乱码，甚至直接报错：

UnicodeEncodeError: 'gbk' codec can't encode character '\u2611'

这不一定影响最终结果，但看起来很难受，也会干扰错误排查。解决方法是执行检测命令前，先把终端编码切到UTF-8：

chcp 65001

或者在激活虚拟环境后设置环境变量：

set PYTHONIOENCODING=utf-8

我用的是后者，因为只影响当前进程，不会永久修改系统设置。在PowerShell里对应写法是：

$env:PYTHONIOENCODING="utf-8"

5.3 杀毒软件把权重文件当病毒隔离

这个坑有点无语。现代杀毒软件对深度学习模型权重文件特别敏感，因为它们看起来就是一堆不可读的二进制数据，容易被误判为木马。有一次我运行crayfish detect，模型加载进度条走到一半就卡住，也不报错。最后发现是Windows Defender把best.pt权重文件隔离了。

检查方法是打开“Windows安全中心”，进入“病毒和威胁防护”，点击“保护历史记录”，看看有没有关于best.pt或相关文件的警告。如果有，点击“允许”恢复文件，然后把工作目录加入“排除项”。操作方法：设置 -> 更新与安全 -> Windows安全中心 -> 病毒和威胁防护 -> 管理设置 -> 排除项 -> 添加文件夹，把C:\projects\crayfish加进去。这样后续运行就不会再被拦截。

5.4 CUDA版本不匹配：明明有显卡却用不上GPU

如果你有NVIDIA显卡，也装了CUDA，但运行时不报错，只是速度没有明显提升，或者报错：

AssertionError: Torch not compiled with CUDA enabled

大概率是PyTorch版本和你装的CUDA不匹配。PyTorch的CUDA版本是编译时就固定好的，不是说你装了CUDA 12.1 PyTorch就会自动用它。需要在安装PyTorch时就指定对应的CUDA版本。

比如你想用CUDA 12.1版PyTorch，安装命令是：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

这里一定不要用默认PyPI源装PyTorch，默认源装的是CPU版。我一开始用默认源装完，查torch.cuda.is_available()一直返回False，查了一圈才发现问题在源上。装完后，再安装“小龙虾”时注意不要覆盖PyTorch版本，可以加--no-deps参数只装项目本体。

5.5 pip依赖冲突：装什么都要求“重新安装”的恶性循环

Windows上pip解析依赖的规则有点轴，有时候你安装A包，它检测到系统中B包版本不满足要求，就直接把B包强制升级或降级，然后又把C包给牵连了。最后依赖关系一团糟。

我的建议是，所有依赖的安装顺序都基于项目自带的requirements.txt，不要自己一个个装。如果安装过程中某个包版本被自动改了，导致其他项目起不来，那就在虚拟环境里重建一个环境，不要试图修复。虚拟环境的优势就在这里，破坏了大不了删掉重建，几分钟的事。

6. 装完不等于会用：把小龙虾装进自己的脚本和项目

6.1 用Python API做更精细的控制

命令行工具适合快速看效果，但要做批量处理和个性化分析，还是直接用Python API更方便。“小龙虾”的核心Detector类使用很简单：

from crayfish_pose import Detector detector = Detector(device='cpu', conf_threshold=0.35) image = cv2.imread('shrimp.jpg') result = detector.detect_frame(image) for keypoint_name, coords in result.keypoints.items(): print(keypoint_name, coords)

这里device='cpu'是强制使用CPU推理；如果你的环境支持GPU，可以改成device='cuda'。detect_frame返回的结果里有目标框、每个关键点的坐标和置信度，可以直接拿来做可视化。我以前跑人体姿态估计，类似的代码写过几百遍，这套API的手感和OpenPose封装差不多，上手成本很低。

6.2 批量处理一整个文件夹的虾图

如果要分析一个T摄像头拍摄的几百张照片，逐张手动跑肯定不现实。写个小脚本可以一次性处理完：

import os from crayfish_pose import Detector import cv2 import json detector = Detector(device='cpu') input_dir = 'shrimp_photos' output_data = [] for filename in os.listdir(input_dir): if not filename.lower().endswith(('.jpg', '.png', '.jpeg')): continue filepath = os.path.join(input_dir, filename) image = cv2.imread(filepath) result = detector.detect_frame(image) output_data.append({ 'file': filename, 'keypoints': result.keypoints.to_dict() }) with open('all_keypoints.json', 'w', encoding='utf-8') as f: json.dump(output_data, f, ensure_ascii=False)

这个脚本跑完，你就能得到整个图片集的关键点数据库。后面不管是算螯肢的平均伸展角度，还是按时间段看尾扇摆动节奏，都有数据基础了。

6.3 如何从关键点算出“舞步”

回到“跳探戈的小龙虾”这个场景。如果你想让动画效果更准确一点，不只是画关键点，还想判断它什么时候在“跳舞”，可以算左右螯肢尖端与头胸甲中央之间的角度变化。当左右螯肢尖端交替划过最大角度，并且腹节屈伸频率稳定，我就可以说这个动作已经符合“探戈步”的特征了。

实现方式很简单，从keypoints.json中提取左螯肢尖端和头胸甲中央的坐标，用math.atan2计算向量角度，然后做滑动窗口平滑。下面是一段简化示例：

import math def angle_between(p1, p2): return math.degrees(math.atan2(p2[1] - p1[1], p2[0] - p1[0])) claw_tip = (kpt['left_claw_tip'][0], kpt['left_claw_tip'][1]) thorax_center = (kpt['thorax_center'][0], kpt['thorax_center'][1]) angle = angle_between(thorax_center, claw_tip)

把每一帧的角度算出来，按时间画折线图，你会看到一组近似正弦波的曲线。振幅大、周期稳的片段，就是“小龙虾跳探戈”最精彩的部分，也是整段视频里最适合做成动图的片段。

6.4 最后的实战建议：把项目固化成可复用的环境

这个项目整体跑通之后，我建议把当前环境里的依赖版本记录到文件中，方便以后在别的机器上快速复现。执行：

pip freeze > requirements-lock.txt

下次换一台Windows电脑，重新创建虚拟环境后，直接：

pip install -r requirements-lock.txt

就能完全复刻当前环境。如果别人没有Python环境，也可以用PyInstaller把脚本打包成exe，打包时注意把模型权重文件作为额外数据加进去，避免运行时找不到。

我个人的习惯是，每折腾完一个像“小龙虾”这样的工具环境，都会顺手把这些坑和命令行记录到自己的笔记里。装第一次可能需要一小时，记下来之后，装第二台机器十五分钟内搞定。这也是我写这篇文章的初衷：把Windows上看起来乱七八糟的深度学习环境安装问题，整理成一条能稳定复现的路。