安装 CASSIA

首先，使用 pip 安装 CASSIA 包：

pip install CASSIA
bash

导入 CASSIA

import CASSIA
Python

命令行界面

Python 包也会安装 cassia 命令，适合 Claude Code、Codex CLI、Cursor Agent 这类 agent-native 工作流。CLI 可以走标准 CASSIA API provider，也可以调用本机 agent CLI 或自定义 shell 命令。

cassia doctor
cassia backends list
cassia examples --out cassia_example
cassia validate markers.csv

cassia annotate \
  --input markers.csv \
  --backend codex-cli \
  --tissue brain \
  --species human \
  --out runs/brain_codex

cassia boost query \
  --markers raw_findallmarkers.csv \
  --cluster 3 \
  --genes CD3D,CD3E,TRAC

cassia boost run \
  --run runs/brain_codex \
  --markers raw_findallmarkers.csv \
  --cluster 3 \
  --backend codex-cli

cassia boost auto \
  --run runs/brain_codex \
  --markers raw_findallmarkers.csv \
  --backend codex-cli \
  --max-clusters 5

cassia subcluster run \
  --markers cd8_subcluster_markers.csv \
  --major-cluster-info "CD8 T cell in human tumor" \
  --backend codex-cli \
  --out runs/cd8_subcluster

cassia consensus \
  --inputs runs/brain_codex/summary.csv runs/brain_claude/summary.csv \
  --out runs/brain_consensus.csv
bash

agent CLI backend 不需要 CASSIA API key；它会复用本机工具自己的登录状态。API backend 仍然使用下面介绍的 API key。cassia examples 会生成一个可直接运行的 mini project， 里面包含 marker table、consensus 输入、shell 脚本和离线 toy agent。cassia validate 会在 annotation 前检查 marker CSV 结构、自动识别到的列、ranking column 和每个 cluster 准备出的 marker 数量。cassia boost auto 会自动优先处理低置信度、疑似混合 或证据不明确的 cluster，并在 RUN/boost/_auto 下生成汇总 CSV/HTML 报告。cassia subcluster run 会读取某个 parent cluster 内部的 subcluster marker table，输出 subcluster 注释 CSV/HTML 报告。cassia consensus 会对多个 CASSIA summary/subcluster CSV 做本地确定性投票，并生成 CSV/HTML consensus 报告，不调用 LLM。

设置 API 密钥

要使用 OpenAI 的 GPT-4、Anthropic 的 Claude 或通过 OpenRouter 使用模型，您首先需要从提供商处获取 API 密钥，然后使用 set_api_key 函数设置您的 API 密钥。

注意：使用 API backend 的 CASSIA 工作流需要至少一个 API 密钥。

您只需选择一个提供商。 推荐使用 OpenRouter，因为它提供多种模型的访问。您也可以使用**自定义 API 提供商**，如 DeepSeek 或本地 LLM。

# 设置 API 密钥（选择一个提供商）
CASSIA.set_api_key("your-openrouter-key", provider="openrouter")  # 推荐
# CASSIA.set_api_key("your-openai-key", provider="openai")
# CASSIA.set_api_key("your-anthropic-key", provider="anthropic")
Python

• 将 "your-key" 替换为您的实际 API 密钥。
• 根据您的提供商，将 provider 设置为 "openai"、"anthropic" 或 "openrouter"。

验证 API 密钥

您可以在运行分析之前验证 API 密钥是否正常工作：

# 验证所有已配置的提供商
CASSIA.validate_api_keys(force_revalidate=True)

# 验证特定提供商
CASSIA.validate_api_keys("openai", force_revalidate=True)
Python

如何选择模型和提供商

有三个提供商可供选择：openrouter、openai 和 anthropic。每个提供商都有自己的模型和定价。 注意，模型名称必须完全按照下面所示设置，否则将找不到模型。

中国大陆用户注意：OpenAI 和 Anthropic 在中国大陆无法直接访问。建议使用 OpenRouter（可访问所有主流模型）、DeepSeek、智谱 GLM、Moonshot Kimi 等国内可访问的提供商，或使用 本地 LLM（如 Ollama）。详见下方 其他提供商 和 本地 LLM 部分。

OpenRouter

OpenRouter 是一个平台，提供对主要提供商支持的几乎所有模型的访问。建议使用 OpenRouter，因为它具有更高的速率限制，并且可以访问包括开源选项在内的各种模型。

• anthropic/claude-sonnet-4.6: 当前默认的高性能模型。
• openai/gpt-5.4: 平衡的选项。
• google/gemini-3-flash-preview: 性能最好的低成本模型之一。

OpenAI

• gpt-5.4: 高性能模型。

Anthropic

• claude-sonnet-4.6: 高性能模型。

其他提供商

这些模型可以通过其自有 API 使用。设置方法请参阅 自定义 API 提供商。

• deepseek-chat (DeepSeek v3.2): 高性能，价格实惠。提供商：https://api.deepseek.com
• glm-5 (GLM 4.6): 快速且经济实惠。提供商：https://api.z.ai/api/paas/v4/
• kimi-k2.5 (Kimi K2): 强大的推理能力。提供商：https://api.moonshot.cn/v1

本地 LLM

• gpt-oss:20b: 可通过 Ollama 在本地运行。适合大批量分析，准确率可接受。设置方法请参阅 本地 LLM。

智能模型设置（推荐）

CASSIA 包含一个智能模型选择系统，允许您使用简单的别名或“层级”代替记住确切的模型版本字符串。这使您的代码对模型版本更新更具鲁棒性。

层级快捷方式

您可以将这些快捷方式与任何提供商一起使用，以获取适合您需求的模型：

• "best": 选择性能最高的模型（例如，gpt-5.4，claude-opus-4.6）
• "balanced": 选择性能和成本平衡良好的模型（例如，gpt-4o，claude-sonnet-4.6）
• "fast": 选择最快/最便宜的模型（例如，gpt-5.4-mini，claude-haiku-4.5）

示例：

# 这将自动为 OpenAI 选择最佳模型
CASSIA.runCASSIA_pipeline(..., model = "best", provider = "openai")
Python

模糊匹配和别名

您也可以使用常用名称，CASSIA 将把它们解析为正确的版本：

• "gpt" -> 解析为 gpt-5.4 (用于 OpenAI)
• "claude" -> 解析为 claude-sonnet-4.6 (用于 Anthropic)
• "gemini" -> 解析为 google/gemini-3-flash-preview (用于 OpenRouter)

自定义 API 提供商

CASSIA 支持任何兼容 OpenAI 的 API 端点，让您可以使用自定义提供商，如 DeepSeek、本地 LLM 服务器或其他第三方服务。

中国大陆用户推荐：由于 Claude 和 GPT 等模型在中国大陆可能存在访问限制，我们推荐使用 DeepSeek。DeepSeek 是中国公司开发的高性能大语言模型，性能与 GPT-4o 相当，价格实惠，访问稳定。

设置自定义提供商

使用自定义 API 提供商时，将完整的基础 URL 作为 provider 参数：

# 为自定义提供商设置 API 密钥
CASSIA.set_api_key("your-api-key", provider="https://api.your-provider.com")

# 在分析中使用
CASSIA.runCASSIA_batch(
    marker=markers,
    output_name="results",
    provider="https://api.your-provider.com",
    model="your-model-name",
    tissue="brain",
    species="human"
)
Python

DeepSeek 使用示例（推荐）

DeepSeek 提供高性能模型，价格实惠，特别适合中国用户：

1. 从 DeepSeek 开放平台 获取 API 密钥
2. 在 CASSIA 中配置：

CASSIA.set_api_key("your-deepseek-key", provider="https://api.deepseek.com")

CASSIA.runCASSIA_pipeline(
    output_file_name="analysis",
    marker=markers,
    annotation_provider="https://api.deepseek.com",
    annotation_model="deepseek-chat",
    tissue="brain",
    species="human"
)
Python

本地 LLM（Ollama、LM Studio）

为了完全的数据隐私和零 API 费用，您可以在本地运行 LLM。CASSIA 支持任何兼容 OpenAI 的本地服务器。

本地 URL 无需 API 密钥。

Ollama 设置

1. 从 ollama.ai 安装 Ollama
2. 拉取模型：ollama pull gpt-oss:20b
3. Ollama 自动运行在 http://localhost:11434

使用方法

CASSIA.runCASSIA_batch(
    marker=markers,
    output_name="results",
    provider="http://localhost:11434/v1",
    model="gpt-oss:20b",
    tissue="brain",
    species="human"
)
Python

推理深度参数

注意： 此参数仅对 OpenAI GPT-5 系列模型（如 gpt-5.4）有效。推荐通过 OpenRouter 使用，或作为已验证的 OpenAI 用户使用。

reasoning 参数控制兼容模型的推理深度。

语法

# 简单字符串格式
reasoning="high"    # 最大推理深度
reasoning="medium"  # 平衡（推荐用于 GPT-5.1）
reasoning="low"     # 最小推理

# 字典格式（仅限 Python）
reasoning={"effort": "high"}

# 标准模式（无扩展推理）
reasoning=None  # 或省略该参数
Python

提供商说明

• OpenAI 通过 OpenRouter: 完全控制推理参数。推荐使用以避免直接 OpenAI API 所需的身份验证。
• OpenAI 直接访问: 需要身份验证才能使用推理模型。
• Anthropic Claude: 默认自动使用最高推理深度。
• Gemini: 动态思考 - 模型自行决定何时以及思考多少。

建议

• GPT-5.1: 使用 reasoning="medium" - 最高深度可能需要很长时间
• GPT-4o: 无需推理参数仍有出色性能
• Claude: 无需设置 - 自动使用最佳推理
• 一般: 更高深度 = 更长处理时间 + 更高成本

示例：

# 通过 OpenRouter 使用 GPT-5.1 的推理功能
CASSIA.runCASSIA_batch(
    marker=markers,
    output_name="results",
    model="openai/gpt-5.4",
    provider="openrouter",
    reasoning="medium",  # 推荐用于平衡速度/质量
    tissue="brain",
    species="human"
)
Python