4. 配置 Python 分析环境

omicos 二进制本身只是调度内核，真正运行 scanpy / omicverse 的是一个独立的 Python 环境。这一步必须做，否则分析代码会报 scanpy not found。

4.1 最简方式：omicos env setup

omicos 内置了环境管理命令，一键创建分析环境（底层用 uv 管理虚拟环境）：

omicos env setup

它会在默认位置 ~/.omicos/env 创建一个 .venv，并装齐 scanpy、omicverse 等依赖（约 1 GB，首次较慢）。这个命令是幂等的——重复运行不会重装已就绪的环境。

常用参数：

装好后用 doctor 自检：

omicos env doctor

它会报告当前解析到的 kernel 解释器、关键依赖是否就绪、托管环境位置和包管理器，例如：

kernel python : /path/to/omicos-env/.venv/bin/python3
omicverse     : present ✓
managed env   : /Users/you/.omicos/env
uv            : uv

omicverse : present ✓ 表示分析环境已就绪；若显示缺失，说明解释器解析到的 Python 里没装 omicverse，需要检查 OMICOS_KERNEL_PYTHON / OMICOS_ENV_DIR 是否指对了环境。

4.2 指定环境位置：OMICOS_ENV_DIR

默认环境在 ~/.omicos/env。如果你想把环境放到别处（比如数据盘、共享目录），用 OMICOS_ENV_DIR 指定：

# 写进 ~/.zshrc 或 ~/.bashrc，永久生效
export OMICOS_ENV_DIR=$HOME/my-omicos-env

omicos 会在该目录下寻找 .venv/bin/python3 作为 kernel 解释器。

4.3 复用已有的 conda / venv 环境

如果你已经有一个装好了 scanpy/omicverse 的环境，不必重复创建。omicos 解析 Python 解释器时按以下优先级链逐项尝试，命中即用：

OMICOS_KERNEL_PYTHON          # ① 显式指定解释器绝对路径，最高优先
  └─ .kernel_choice           # ② 之前持久化的选择
      └─ OMICOS_ENV_DIR/.venv # ③ omicos 自己的环境
          └─ PYTHON           # ④ PYTHON 环境变量
              └─ CONDA_PREFIX # ⑤ 当前激活的 conda 环境
                  └─ VIRTUAL_ENV   # ⑥ 当前激活的 venv
                      └─ python3   # ⑦ 系统 python3（兜底）

最直接的做法是用 OMICOS_KERNEL_PYTHON 钉死解释器：

export OMICOS_KERNEL_PYTHON=/path/to/your/conda/envs/omicverse/bin/python

注意： 解释器只在启动时检测一次。改了上述任何环境变量后，需要重启 omicos serve / omicos cli 才生效。

4.4 非交互 / 自动化部署：OMICOS_ENV_AUTO

在 CI、Docker、批处理脚本里，你不希望 omicos 卡在"是否安装环境？"的交互提示上。设置：

export OMICOS_ENV_AUTO=1

omicos 首次启动时会自动 uv sync 引导环境而不再询问（会触发约 1.5 GB 下载）。

4.5 远程 kernel：跳过本地环境

如果 kernel 不在本机，而是跑在一个远程 HTTP 服务上，可以让 omicos 直接连过去，跳过本地 Python 环境引导：

export OMICOS_KERNEL_BASE_URL=http://kernel-host:5173
# 或启动时传 --kernel-base-url http://kernel-host:5173

设置后，omicos 不再尝试在本地创建/检测 Python 环境，所有代码执行转发到该远程 kernel。这在"瘦客户端 + 重算力服务器"的架构里很有用。

小结

环境就绪后，进入第 5 章：首次登录。