xCOMET MCP Server

xCOMET MCP 服务

日语版 README 请点击这里

⚠️ 这是一个非官方社区项目，与 Unbabel 无关。

由 xCOMET（eXplainable COMET）驱动的翻译质量评估 MCP 服务。

🎯 概述

xCOMET MCP 服务为 AI Agent 提供机器翻译质量评估功能。它集成了 Unbabel 的 xCOMET 模型，可提供：

• 质量评分：以 0-1 之间的分数表示翻译质量
• 错误检测：识别错误片段并标注严重程度（轻微／严重／危急）
• 批量处理：高效评估多个翻译对（优化为仅加载一次模型）
• GPU 支持：可选 GPU 加速，以提升推理速度

graph LR
    A[AI Agent] --> B[Node.js MCP Server]
    B -- stdio JSON-RPC --> C[Python Worker]
    C --> D[xCOMET Model<br/>Persistent in Memory]
    D --> C
    C --> B
    B --> A

    style D fill:#9f9

🔧 前置条件

Python 环境

• 推荐使用 Python 3.9 - 3.12（xCOMET 依赖项尚不支持 3.13 及更高版本）

xCOMET 需要安装多个软件包的 Python 环境。建议使用虚拟环境：

# If using uv (recommended - auto-downloads the correct Python version)
uv venv ~/.xcomet-venv --python 3.12
source ~/.xcomet-venv/bin/activate
uv pip install "unbabel-comet>=2.2.7,<3.0"

# Or using standard venv (requires Python 3.9-3.12 already installed)
python3 -m venv ~/.xcomet-venv
source ~/.xcomet-venv/bin/activate  # Windows: ~/.xcomet-venv\Scripts\activate
pip install "unbabel-comet>=2.2.7,<3.0"

为什么使用 Python 3.9-3.12？ unbabel-comet 声明了 numpy = "^1.20.0"，因此 会解析为 numpy 1.x。numpy 1.x 的最后一个版本 1.26.4 仅提供 cp39-cp312 的 wheel。 在 Python 3.13 或更高版本中，pip 必须从源码构建 numpy。

注意（v0.5.0+）：Python worker 现在通过 stdin/stdout 与 Node.js 通信 （按行分隔的 JSON-RPC）。不再需要 FastAPI、uvicorn 和 pydantic，只需安装 unbabel-comet。

注意：与 Claude Desktop 或其他 MCP 宿主搭配使用时，请将 XCOMET_PYTHON_PATH 设置为虚拟环境中的 Python 路径（参见配置）。

模型下载

重要：XCOMET-XL 和 XCOMET-XXL 是 HuggingFace 上的受限模型。你必须：

1. 创建一个 HuggingFace 账号

2. 访问 Unbabel/XCOMET-XL 并申请访问权限

3. 进行身份验证，可通过 CLI：

   source ~/.xcomet-venv/bin/activate
   hf auth login
   

   （huggingface-cli login 仍可使用，但从 huggingface_hub 0.34 起会打印弃用警告； hf 是当前使用的命令。）

   也可以在 MCP 宿主的 env 块中设置 HF_TOKEN。如果宿主在未执行 CLI 登录的环境中启动服务， 请使用此方式：

   "env": {
     "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3",
     "HF_TOKEN": "hf_..."
   }
   

   huggingface_hub 会优先读取 HF_TOKEN，如果不存在，则使用 hf auth login 写入的令牌文件。

Unbabel/wmt22-comet-da 无需身份验证（但需要参考译文）。

完成身份验证后，下载模型（XL 约 14GB，XXL 约 42GB）：

source ~/.xcomet-venv/bin/activate
python -c "from comet import download_model; download_model('Unbabel/XCOMET-XL')"

模型的存储位置

不在虚拟环境中。 虚拟环境存放 Python 包；模型权重则存放在 huggingface_hub 缓存中，这是一个独立目录，供这台机器上所有从 Hub 下载内容的工具共享。

~/.xcomet-venv/                              ← Python packages only
└── lib/python3.x/site-packages/
    ├── comet/                               unbabel-comet itself
    └── torch/  transformers/  ...           its dependencies

~/.cache/huggingface/                        ← the model weights live here
└── hub/
    └── models--Unbabel--XCOMET-XL/
        ├── blobs/                           the actual ~14GB checkpoint
        └── snapshots/<revision>/
            ├── checkpoints/model.ckpt       what download_model() returns
            └── hparams.yaml

download_model() 会将 cache_dir=None 传递给 snapshot_download()，因此由 huggingface_hub 决定存储位置：HF_HUB_CACHE，默认值为 HF_HOME/hub；而 HF_HOME 的默认值为 $XDG_CACHE_HOME/huggingface（如果未设置 XDG_CACHE_HOME，则为 ~/.cache/huggingface）。

有几点值得了解：

• 重建或删除虚拟环境不会重新下载模型。
• 多个虚拟环境以及其他基于 Hub 的工具会共享同一份副本。
• 虚拟环境目录的大小不包含这 14GB。使用 hf cache scan 查看磁盘上实际存储的内容，并使用 hf cache delete 删除某个版本。

若要将检查点存放在其他位置（例如更大的卷或共享驱动器），请设置 XCOMET_SAVING_DIRECTORY（v0.7.0+）或标准变量 HF_HOME。这两个变量都会在下载时读取，因此已下载到默认位置的模型不会被移动，而是会重新下载到新位置。

Node.js

• Node.js >= 22.0.0（与 package.json 中的 engines.node 一致；CI 使用 22 和 24）
• npm 或 yarn

📦 安装

注意：如果你只想使用 xCOMET MCP Server，则无需克隆此仓库。请安装 Python 环境和模型（参见先决条件），然后使用 npx（参见用法）。以下章节仅供贡献者和本地开发使用。

本地开发

供贡献者和本地开发使用：

# Clone the repository
git clone https://github.com/shuji-bonji/xcomet-mcp-server.git
cd xcomet-mcp-server

# Set up Python virtual environment and install dependencies
uv venv .venv --python 3.12    # or: python3 -m venv .venv
source .venv/bin/activate
pip install -r python/requirements.txt

# Install Node.js dependencies and build
npm install
npm run build

🚀 用法

使用 Claude Desktop（npx）

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server@latest"],
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

提示：如果你已在系统范围内安装 Python 包或使用 pyenv，可以省略 XCOMET_PYTHON_PATH（自动检测会找到它）。详情请参见 Python 路径自动检测。

使用 Claude Code

claude mcp add xcomet --env XCOMET_PYTHON_PATH=~/.xcomet-venv/bin/python3 -- npx -y xcomet-mcp-server@latest

全局安装

如果你更倾向于全局安装：

npm install -g xcomet-mcp-server

然后进行配置：

{
  "mcpServers": {
    "xcomet": {
      "command": "xcomet-mcp-server",
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

本地开发构建

如果你已在本地克隆并构建此仓库（参见安装）：

{
  "mcpServers": {
    "xcomet": {
      "command": "node",
      "args": ["/path/to/xcomet-mcp-server/dist/index.js"],
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

🛠️ 可用工具

xcomet_evaluate

评估单个源文本与译文对的翻译质量。

参数：

名称	类型	必填	描述
source	字符串	✅	原始源文本
translation	字符串	✅	要评估的译文
reference	字符串	❌	参考译文
source_lang	字符串	❌	源语言代码（ISO 639-1）
target_lang	字符串	❌	目标语言代码（ISO 639-1）
response_format	"json" | "markdown"	❌	输出格式（默认："json"）
use_gpu	布尔值	❌	使用 GPU 进行推理（默认：false）

示例：

{
  "source": "The quick brown fox jumps over the lazy dog.",
  "translation": "素早い茶色のキツネが怠惰な犬を飛び越える。",
  "source_lang": "en",
  "target_lang": "ja",
  "use_gpu": true
}

响应：

{
  "score": 0.847,
  "errors": [],
  "summary": "Good quality (score: 0.847) with 0 error(s) detected."
}

xcomet_detect_errors

重点检测并分类翻译错误。

参数：

名称	类型	必填	描述
source	字符串	✅	原始源文本
translation	字符串	✅	要分析的译文
reference	字符串	❌	参考译文
min_severity	"minor" | "major" | "critical"	❌	最低严重程度（默认："minor"）
response_format	"json" | "markdown"	❌	输出格式
use_gpu	布尔值	❌	使用 GPU 进行推理（默认：false）

xcomet_batch_evaluate

在单个请求中评估多组翻译对。

性能说明：使用持久化服务架构（v0.3.0+）时，模型会一直加载在内存中。批量评估可高效处理所有翻译对，无需重新加载模型。

参数：

名称	类型	必填	描述
pairs	数组	✅	{source, translation, reference?} 对象数组（最多 500 个）
source_lang	字符串	❌	源语言代码
target_lang	字符串	❌	目标语言代码
response_format	"json" | "markdown"	❌	输出格式
use_gpu	布尔值	❌	推理时使用 GPU（默认值：false）
batch_size	数字	❌	批次大小，范围为 1–64（默认值：8）。数值越大，速度越快，但占用的内存也越多

示例：

{
  "pairs": [
    {"source": "Hello", "translation": "こんにちは"},
    {"source": "Goodbye", "translation": "さようなら"}
  ],
  "use_gpu": true,
  "batch_size": 16
}

🔗 与其他 MCP 服务集成

xCOMET MCP Server 专为与其他 MCP 服务协同工作而设计，可实现完整的翻译工作流：

sequenceDiagram
    participant Agent as AI Agent
    participant DeepL as DeepL MCP Server
    participant xCOMET as xCOMET MCP Server
    
    Agent->>DeepL: Translate text
    DeepL-->>Agent: Translation result
    Agent->>xCOMET: Evaluate quality
    xCOMET-->>Agent: Score + Errors
    Agent->>Agent: Decide: Accept or retry?

推荐工作流

1. 使用 DeepL MCP Server（官方版）翻译
2. 使用 xCOMET MCP Server 评估
3. 如果质量低于阈值，则迭代改进

示例：DeepL 与 xCOMET 集成

在 Claude Desktop 中配置这两个服务：

{
  "mcpServers": {
    "deepl": {
      "command": "npx",
      "args": ["-y", "@anthropic/deepl-mcp-server"],
      "env": {
        "DEEPL_API_KEY": "your-api-key"
      }
    },
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server@latest"],
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

然后向 Claude 提问：

“使用 DeepL 将这段文本翻译成日语，然后用 xCOMET 评估翻译质量。如果分数低于 0.8，请提出改进建议。”

⚙️ 配置

环境变量

变量	默认值	描述
XCOMET_MODEL	Unbabel/XCOMET-XL	要使用的 xCOMET 模型
XCOMET_PYTHON_PATH	（自动检测）	Python 可执行文件路径（见下文）
XCOMET_PRELOAD	false	启动时预加载模型（v0.3.1+）
XCOMET_DEBUG	false	启用详细调试日志（v0.3.1+）
XCOMET_NUM_WORKERS	1	model.predict() 的 DataLoader 工作进程数（v0.6.0+）。运行大批次时，尤其是在 GPU 上运行时，可增大此值以更充分地利用空闲 CPU 核心。无效值会静默回退为 1。
XCOMET_SAVING_DIRECTORY	（HuggingFace 缓存）	下载检查点的目录（v0.7.0+）。未设置时，模型会存入 huggingface_hub 缓存（HF_HOME，默认值为 ~/.cache/huggingface）。设置此项可将 14GB（XL）或 43GB（XXL）的检查点存放到其他卷。
XCOMET_LOCAL_FILES_ONLY	false	仅从本地缓存加载检查点（v0.7.0+）。设为 true 可在不联网的情况下启动；此时模型必须已下载。
HF_TOKEN	（未设置）	huggingface_hub 读取的 HuggingFace 访问令牌。对于受限模型（XCOMET-XL、XCOMET-XXL 和 CometKiwi 模型），可用此令牌代替 hf auth login。

模型选择

根据质量和性能需求选择模型：

模型	参数量	大小	内存	参考译文	HF 身份验证	质量	使用场景
Unbabel/XCOMET-XL	3.5B	~14GB	~8-10GB	可选	✅ 必需	⭐⭐⭐⭐	推荐用于大多数场景
Unbabel/XCOMET-XXL	10.7B	~42GB	~20GB	可选	✅ 必需	⭐⭐⭐⭐⭐	质量最高，但需要更多资源
Unbabel/wmt22-comet-da	580M	~2GB	~3GB	必需	不需要	⭐⭐⭐	轻量、加载更快

重要：XCOMET-XL 和 XCOMET-XXL 是 HuggingFace 上的受限模型。每个模型都需要单独申请访问权限。身份验证设置请参阅模型下载。

重要：wmt22-comet-da 需要提供 reference 译文才能进行评估。XCOMET 模型支持无参考译文评估。

提示：如果遇到内存问题或模型加载缓慢，可尝试使用 Unbabel/wmt22-comet-da，以稍低的准确率换取更快的运行速度（但请记得提供参考译文）。

如需使用其他模型，请设置 XCOMET_MODEL 环境变量：

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server@latest"],
      "env": {
        "XCOMET_MODEL": "Unbabel/XCOMET-XXL"
      }
    }
  }
}

Python 路径自动检测

服务器会自动检测已安装 unbabel-comet 的 Python 环境：

1. XCOMET_PYTHON_PATH 环境变量（如果已设置）
2. pyenv 版本（~/.pyenv/versions/*/bin/python3）——检查是否安装 comet 模块
3. Homebrew Python（/opt/homebrew/bin/python3、/usr/local/bin/python3）
4. 回退方案：python3 命令

即使 MCP 主机（例如 Claude Desktop）使用的 Python 与终端中的 Python 不同，也能确保服务器正常运行。

示例：显式配置 Python 路径

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server@latest"],
      "env": {
        "XCOMET_PYTHON_PATH": "/Users/you/.pyenv/versions/3.11.0/bin/python3"
      }
    }
  }
}

⚡ 性能

持久化 Worker 架构（v0.3.0+，stdio 自 v0.5.0 起）

服务器使用持久化 Python Worker 进程，将 xCOMET 模型保留在内存中。Node.js MCP 服务器通过 stdin/stdout 使用按行分隔的 JSON-RPC 协议与 Worker 通信——无需本地 HTTP 监听器、无需绑定端口，也无需 FastAPI。

请求	时间	说明
首次请求	~25-90s	模型加载时间（因模型大小而异）
后续请求	~500ms	模型已加载

与每次都重新加载模型相比，这能让连续评估的速度提升 177 倍。

预加载（v0.3.1+）

启用 XCOMET_PRELOAD=true，即可在服务器启动时预加载模型：

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server@latest"],
      "env": {
        "XCOMET_PRELOAD": "true"
      }
    }
  }
}

启用预加载后，所有请求都很快（~500ms），包括首次请求。

graph LR
    A[MCP Request] --> B[Node.js Server]
    B -- stdio JSON-RPC --> C[Python Worker]
    C --> D[xCOMET Model<br/>in Memory]
    D --> C
    C --> B
    B --> A

    style D fill:#9f9

批处理优化

xcomet_batch_evaluate 工具只需加载一次模型，即可处理所有成对数据：

成对数据	预计时间
10	~30-40 sec
50	~1-1.5 min
100	~2 min

GPU 与 CPU 性能

模式	100 对（预计）
CPU (batch_size=8)	~2 min
GPU (batch_size=16)	~20-30 sec

注意：GPU 需要兼容 CUDA 的硬件，以及支持 CUDA 的 PyTorch。如果无法使用 GPU，请设置 use_gpu: false（默认值）。

最佳实践

1. 让持久化服务器正常工作

在 v0.3.0+ 中，模型会保留在内存中。现在多次调用 xcomet_evaluate 的效率更高：

✅ Fast: First call loads model, subsequent calls reuse it
   xcomet_evaluate(pair1)  # ~90s (model loads)
   xcomet_evaluate(pair2)  # ~500ms (model cached)
   xcomet_evaluate(pair3)  # ~500ms (model cached)

2. 处理大量成对数据时，使用批量评估

✅ Even faster: Batch all pairs in one call
   xcomet_batch_evaluate(allPairs)  # Optimal throughput

3. 内存注意事项

• XCOMET-XL 需要约 8-10GB RAM
• 对于大型批次（500 对），请确保有足够的内存
• 如果内存有限，请拆分为较小的批次（100-200 对）

自动重启（v0.3.1+）

服务器会在发生故障时自动恢复：

• 每隔 30 秒监控运行状况
• 连续 3 次运行状况检查失败后重启
• 放弃前最多尝试重启 3 次

📊 质量分数解读

分数范围	质量	建议
0.9 - 1.0	优秀	可投入使用
0.7 - 0.9	良好	建议进行少量审核
0.5 - 0.7	一般	需要译后编辑
0.0 - 0.5	较差	建议重新翻译

该分数能告诉你什么，不能告诉你什么

该分数回答的是“这段文本读起来像是对该源文本的翻译吗？”，而且很擅长回答这个问题。但它无法回答“这段译文中的事实是否正确”。这两个问题并不等同，而当输出内容是合同、剂量、价格或操作流程时，这一点至关重要。

以下数据是在此服务中通过 CPU 使用 Unbabel/XCOMET-XL 测得的。前两行是该指标表现出色的情况；后两行则是它无法胜任的情况。

源文本	译文	分数
ファイルを保存せずに終了しますか？	您要在不保存文件的情况下退出吗？	0.956
ファイルを保存せずに終了しますか？	每隔一个星期四，山峦便会唱起紫色的歌。	0.212
保証期間は購入日から一年間です。	保修期自购买之日起为十年。	1.000
電源を切ってから、カバーを取り外してください。	请先取下盖子，然后关闭电源。	1.000

与源文本毫不相关的译文，分数会降至约 0.2，这正是你希望看到的结果。但如果译文流畅，却把一年换成十年，或颠倒了两条指令的顺序，分数仍会达到满分 1.000。提供参考译文也无济于事：即使将 The warranty period is one year from the date of purchase. 作为参考译文，“ten years”这版译文的分数仍为 0.983。

这并非此服务或 xCOMET 本身的缺陷。这是神经机器翻译指标的已知特性：它们“难以检测某些可视为严重错误的现象，例如实体和数字的偏差”(Rei et al., 2023)。

正确使用该指标

适用场景

• 对一组译文进行排序或分流——确定优先审查哪些片段，或判断两个机器翻译系统中哪个在你的数据上表现更好。
• 发现充分性崩溃——输出被截断、粘贴了错误的片段、模型偏离主题，或未经翻译直接透传。
• 在固定测试集上跟踪质量随时间的变化，比较不同运行结果，而非与绝对标准线比较。
• 作为人工审校前的初筛工具，决定将人工审校时间用在何处。

不适用场景

• 将其作为唯一的发布门槛，用于任何一个数字或名称出错就会导致失败的内容——例如医疗、法律、财务或安全说明。请使用能够实际比较数字、日期、单位、货币和命名实体的规则，单独检查这些内容；该分数不会替你完成这项工作。
• 对质量作绝对评价。0.95 不代表“95% 正确”，而且该数值不能跨模型、语言对或片段长度进行比较。
• 极短的片段（UI 标签、单个词），因为此时分数会趋于饱和，不再具有区分能力。

请将 xcomet_detect_errors 与分数结合使用。 错误片段会标出模型认为出错的位置，并附上 MQM 严重程度。与单独看任一数值相比，高分但包含 critical 级别片段是更有用的信号。

🔍 故障排除

常见问题

"No module named 'comet'"

原因：Python 环境中未安装 unbabel-comet。

解决方案：

# Check which Python is being used
python3 -c "import sys; print(sys.executable)"

# If using a virtual environment, make sure it's activated
source .venv/bin/activate
pip install -r python/requirements.txt

# For MCP hosts (e.g., Claude Desktop), specify the venv Python path
export XCOMET_PYTHON_PATH=~/.xcomet-venv/bin/python3

Homebrew 升级后 venv 无法使用

症状：出现 zsh: no such file or directory: .venv/bin/python3，或在已激活的 venv 中，python3 解析到的解释器与该 venv 的解释器不同，或原本可用的 venv 中出现 No module named 'comet'。

原因：venv 不包含解释器，而是保存了创建该 venv 时所用解释器的绝对 符号链接，记录在 pyvenv.cfg 中：

home = /opt/homebrew/opt/[email protected]/bin
version = 3.14.3

当 Homebrew 升级或移除该 formula 时，链接会失效，venv 也就无法使用了。lib/python3.x/site-packages/ 仍然存在，但没有可用的解释器来运行其中的内容。

检查：

ls -l .venv/bin/python3 && .venv/bin/python3 -V
cat .venv/pyvenv.cfg

解决方案：重新创建 venv。uv venv --python 3.12 更耐用， 因为 uv 会自行下载并固定该解释器，而不是借用 Homebrew 当前的解释器。

rm -rf .venv
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install "unbabel-comet>=2.2.7,<3.0"

重新安装软件包需要几百 MB，但不会重新下载模型：检查点位于 huggingface_hub 缓存中，而不在 venv 中（参见模型存储位置）。

升级后启动了旧版本

症状：你确认已发布的修复在运行中的服务里缺失。日志中的 启动横幅显示的是旧版本。

grep "running on stdio" ~/Library/Logs/Claude/mcp-server-xcomet.log | tail -1
xcomet-mcp-server v0.6.3 running on stdio

（在 macOS 上，Claude Desktop 会将每个 MCP 服务的 stderr 写入 ~/Library/Logs/Claude/mcp-server-<name>.log。）

原因：npx 会从 npm 缓存的注册表元数据中解析 latest，并运行它已安装在 ~/.npm/_npx 下的副本。发布新版本后的一段时间内，该副本仍是旧版本。它最终会自行更新，但更新时间无法由你决定。@latest 也无法解决这个问题——对 npm 来说，它与不写版本号的含义相同。

解决方案：清除 npx 缓存，然后重启 MCP 主机。

rm -rf ~/.npm/_npx

ps 会显示正在运行的副本，以及它来自哪个缓存目录。

ps -axo pid,command | grep xcomet-mcp-server | grep -v grep

如需使用已知版本，请固定到确切版本：[email protected]。

模型下载失败或超时

原因：大型模型文件（XL 约为 14GB）需要稳定的互联网连接。XCOMET 模型还需要 HuggingFace 身份验证（参见模型下载）。

解决方案：

# Authenticate with HuggingFace (required for XCOMET-XL/XXL)
hf auth login          # or: export HF_TOKEN=hf_...

# Pre-download the model manually
python -c "from comet import download_model; download_model('Unbabel/XCOMET-XL')"

如果下载中断，缓存中会保留一个快照目录，但其中没有 checkpoints/model.ckpt。服务会报告该路径并提示你删除此目录；hf cache scan 会列出它的位置。

未检测到 GPU

原因：安装的 PyTorch 不支持 CUDA。

解决方案：

# Check CUDA availability
python -c "import torch; print(torch.cuda.is_available())"

# If False, reinstall PyTorch with CUDA
pip install torch --index-url https://download.pytorch.org/whl/cu118

Mac 上性能缓慢（MPS）

原因：Mac MPS（Metal Performance Shaders）与某些操作存在兼容性问题。

解决方案：服务会自动使用 num_workers=1，以兼容 Mac MPS。若要在 Mac 上获得最佳性能，请使用 CPU 模式（use_gpu: false）。

内存占用过高或崩溃

原因：XCOMET-XL 需要约 8-10GB RAM。

解决方案：

1. 使用持久服务（v0.3.0+）：模型只加载一次并常驻内存，避免内存反复飙升
2. 使用较轻量的模型：设置 XCOMET_MODEL=Unbabel/wmt22-comet-da，以降低内存占用（约 3GB）
3. 减小批次大小：对于较大的批次，分成更小的块处理（100-200 对）
4. 关闭其他应用程序：运行大型评测前释放 RAM

# Check available memory
free -h  # Linux
vm_stat | head -5  # macOS

VS Code 或 IDE 在评测过程中崩溃

原因：xCOMET 模型占用大量内存（XL 约为 8-10GB）。

解决方案：

• 在 v0.3.0+ 中，模型只加载一次并常驻内存（不会反复加载）
• 如果内存仍然不足，请使用较轻量的模型：XCOMET_MODEL=Unbabel/wmt22-comet-da
• 评测前关闭其他占用大量内存的应用程序

获取帮助

如果遇到问题：

1. 查看 GitHub Issues
2. 启用调试日志（查看 Claude Desktop 的 Developer Mode 日志，或设置 XCOMET_DEBUG=true）
3. 提交新问题，并附上：
   • 你的操作系统和 Python 版本
   • 错误消息
   • 配置（请勿包含敏感数据）

🧪 开发

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run tests (Vitest)
npm test

# Run the Python-side tests (pytest only — no comet, no model)
npm run test:python

# Test with MCP Inspector
npm run inspect

npm run test:python 会调用 python3 -m pytest，因此必须能从 PATH 中的某个 python3 导入 pytest。仅激活 xCOMET 虚拟环境并没有帮助，除非其中安装了 pytest。以下任一方式都可行：

uvx pytest tests/test_server.py -q                    # nothing to install
~/.xcomet-venv/bin/python -m pip install pytest       # add it to the xCOMET venv
python3 -m venv .venv-dev && .venv-dev/bin/pip install pytest

tests/README.md 介绍了每个测试套件、其覆盖范围及其用途。

📋 更新日志

请参阅 CHANGELOG.md 查看版本历史和更新。

📝 许可证

MIT 许可证——详情请参阅 LICENSE。

🙏 致谢

• 感谢 Unbabel 提供 xCOMET 模型
• 感谢 Anthropic 提供 MCP 协议
• 感谢 Model Context Protocol 社区

📚 参考资料

• xCOMET 论文
• COMET 框架
• BLEU Meets COMET（Rei 等，2023） — 关于神经指标遗漏实体和数字错误的问题；这是分数能告诉你什么、不能告诉你什么一节的依据
• Hugging Face Hub 缓存布局
• MCP 规范