Skip to content

linux_cli.md

Latest commit

 

History

History
122 lines (89 loc) · 5.33 KB

linux_cli.md

File metadata and controls

122 lines (89 loc) · 5.33 KB
Raw

ChatCellAnno 命令行工具 (Linux / Windows)

命令行版与 GUI 共享同一份核心逻辑 (core/extractor/prompt/parser/enrichment) 和配置， 不依赖 PySide6，非常适合 Linux 服务器、HPC 或 headless 环境使用。

1. 环境配置

# 创建 conda 环境（命令行版不需要 GUI，装到服务器即可）
conda create -n chatcellanno python=3.11 pandas -y
conda activate chatcellanno

# 安装依赖（CLI 最小集合；如需 GUI 请加 PySide6）
pip install -r requirements.txt

# 以开发模式安装，注册 chatcellanno 命令
pip install -e .

提示：requirements.txt 中包含 PySide6/PyInstaller，在纯 CLI 服务器上 可以只装 CLI 需要的子集： pip install pandas pyperclip openai keyring click tabulate gseapy matplotlib

2. 配置 API

CLI 与 GUI 共享 ~/.config/ChatCellAnno/config.json（Windows 为 %APPDATA%\ChatCellAnno）。

# 查看当前配置
chatcellanno config show

# 设置模型与密钥（密钥存入系统凭据管理器 keyring）
chatcellanno config set --base-url https://api.deepseek.com/v1 --model deepseek-chat
chatcellanno config set --api-key sk-xxxx

# 环境自检（依赖 / 配置 / API 连通性）
chatcellanno doctor

3. 常用命令

# 生成提示词（打印到终端）
chatcellanno generate markers.csv --species Human --tissue PBMC --top-n 10

# 生成结构化 JSON 提示词并写入文件
chatcellanno generate markers.csv --mode json -o prompt.json.txt

# 生成提示词 → 直连 API → 终端流式输出
chatcellanno query markers.csv --mode json

# 解析 AI 回复（JSON 优先，表格回退）→ 输出注释表格
chatcellanno parse reply.txt --marker-file markers.csv -o anno.csv

# 功能富集分析（Enrichr 在线 / 本地 gmt）
chatcellanno enrich markers.csv --db GO_Biological_Process_2021
chatcellanno enrich markers.csv --db ./genesets/custom.gmt --no-plot   # --db 为本地文件时自动走本地模式

# 端到端一键注释：提示词 → API → 注释表格（推荐日常使用）
chatcellanno run markers.csv

# 端到端 + 全部输入文件与参数（输出落到 ./result/）
chatcellanno run markers.csv \
    --species Mouse --tissue Brain --top-n 15 --exclude "Doublet" \
    --mode json --matrix expr_matrix.csv --image umap.png \
    --use-enrichment --enrich-db GO_Biological_Process_2021 \
    --no-stream -o ./result/anno

# 交互式多轮对话（可先加载 marker 上下文）
chatcellanno chat markers.csv

run 详细说明（一步到位的端到端注释）

流程：读取 marker 文件与可选上下文 → 生成提示词（默认 json 模式，要求模型输出结构化 JSON）→ 调用配置的 API（终端流式输出）→ 解析 JSON 为注释表格 → 终端打印表格（Cluster / Cell Type / Reasoning）。

输入文件：

文件 是否必需 参数 格式
Marker 基因文件 ✅ 必需 位置参数 CSV/TSV/TXT，需含基因列 (names/gene/symbol/feature) 与聚类列 (group/cluster/leiden/louvain)
表达矩阵 可选 --matrix 聚类为行、基因为列的 CSV/TSV
聚类图（UMAP/t-SNE） 可选 --image 任意图片，以多模态请求发送给 API
本地基因集文件 可选 --enrich-db .gmt/.txt（配合 --use-enrichment）

参数一览：

类别 参数 说明
Marker --species / --tissue / --top-n / --exclude 物种(默认 Human)、组织(默认 PBMC)、Top 数(默认 10)、排除类型
提示词 --mode concise / detailed / json（默认 json，便于解析；detailed 含置信度与文献引用）
上下文 --matrix / --image / --use-enrichment / --enrich-db 表达矩阵、聚类图、富集辅助（在线库名或本地 gmt 路径）
API --base-url / --model / --api-key / --temperature / --max-tokens / --no-stream 覆盖配置文件设置；--api-key 直接传参会留在 shell 历史，建议优先 config set
输出 -o 输出文件前缀

输出文件（传 -o 前缀 时生成，UTF-8）：

文件 内容
{前缀}.csv 注释表格（Cluster, Cell Type, Reasoning）
{前缀}.reply.txt AI 原始回复（可离线再跑 parse 复现）

未配置 API Key 时 run 直接报错并以非零码退出；API 调用失败同样以非零码退出，便于脚本判断成败。

4. 命令一览

子命令 作用
generate 生成 AI 提示词（concise/detailed/json）
query 生成 + 调用 API，终端流式输出，--save 保存回复
parse 解析回复为注释表格，-o 导出 CSV
run 端到端一键注释：提示词 → API → 注释表格，-o 落盘
enrich 功能富集分析（--db 路径存在时自动走本地 gmt，否则 Enrichr 在线库；--local 可强制本地），--no-plot headless
chat 多轮 REPL（/new /save /help /exit）
config show/set 查看/修改 API 配置
doctor 环境自检

5. 常见问题

  • 无桌面环境绘图失败：enrich 加 --no-plot。
  • 中文乱码：设置 export PYTHONIOENCODING=utf-8。
  • 本地模型（Ollama）：config set --base-url http://localhost:11434/v1 --model qwen2.5:14b，--api-key 可随意填。