本教程旨在解决使用`pip install keybert`时常见的安装失败问题，特别是当出现rust/cargo未安装的错误提示时。我们将详细介绍如何正确安装rust及其包管理器cargo，这是keybert及其某些底层组件编译所必需的。通过遵循本指南，用户将能够顺利完成keybert的安装，并开始使用其强大的关键词提取功能。
1. 理解KeyBERT安装失败的根源
在使用pip install keybert安装KeyBERT库时，部分用户可能会遇到一个错误提示，大致内容为：
error: subprocess-exited-with-error × Preparing metadata (pyproject.toml) did not run successfully. │ exit code: 1 ╰─> [6 lines of output] Cargo, the Rust package manager, is not installed or is not on PATH. This package requires Rust and Cargo to compile extensions. Install it through the system's package manager or via https://www.php.cn/link/1c8dcf919f8a604f3a488b0e4b0f1420
这个错误信息清晰地指出，KeyBERT的某些底层依赖（通常是为了性能优化）需要Rust编程语言及其包管理器Cargo来编译扩展模块。如果你的系统中没有安装Rust和Cargo，或者它们不在系统的PATH环境变量中，那么pip就无法完成这些扩展的编译，从而导致安装失败。这与你使用的Python版本（例如Python 3.12或3.8）通常无关，而是缺少了外部的编译工具链。
2. 安装Rust和Cargo
解决这个问题的核心是安装Rust编程语言及其官方推荐的包管理器Cargo。最推荐的安装方式是通过rustup工具。
2.1 通过rustup安装（推荐）
rustup是Rust的官方安装工具，它允许你轻松管理Rust版本和组件。
步骤：
访问官方网站： 打开浏览器，访问Rust官方安装页面：https://www.php.cn/link/1c8dcf919f8a604f3a488b0e4b0f1420。
-
下载并运行安装程序：
Windows用户： 下载rustup-init.exe并运行。按照提示操作，通常选择默认安装选项即可。
-
macOS和Linux用户： 打开终端，输入以下命令并按回车键执行：
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
此命令会下载并执行rustup安装脚本。安装过程中，通常选择默认选项（输入1并回车）即可。安装完成后，脚本会提示你需要将Cargo的bin目录添加到PATH环境变量中。对于大多数用户，这会自动完成。如果提示需要手动设置，请按照提示操作，或关闭并重新打开终端。
2.2 验证Rust安装
安装完成后，为了确保Rust和Cargo已正确安装并添加到系统PATH中，请打开一个新的终端或命令提示符窗口，并执行以下命令：
rustc --version cargo --version
如果安装成功，这些命令将显示Rust编译器（rustc）和Cargo包管理器的版本信息，例如：
rustc 1.76.0 (0a32c735d 2024-02-18) cargo 1.76.0 (c47796e6c 2024-01-25)
如果显示版本信息，则表示Rust环境已准备就绪。
3. 重新安装KeyBERT
在确认Rust和Cargo已正确安装后，你可以尝试再次安装KeyBERT。
-
激活你的Python虚拟环境（如果使用的话）：
# 例如，对于venv source .venv/bin/activate # 或对于conda conda activate your_env_name
-
执行KeyBERT安装命令：
pip install keybert
此时，pip应该能够找到并使用Rust编译器来编译所需的扩展，从而顺利完成KeyBERT的安装。
4. KeyBERT基本使用示例
安装成功后，你可以立即开始使用KeyBERT来提取文本中的关键词。
from keybert import KeyBERT
# 初始化KeyBERT模型
# 默认使用'all-MiniLM-L6-v2'模型，也可以指定其他SentenceTransformer模型
kw_model = KeyBERT()
# 示例文本
document = """
KeyBERT is a minimal and easy-to-use keyword extraction technique.
It leverages BERT embeddings and a simple cosine similarity to find the most
representative words and phrases in a document. The core idea is to create
document embeddings, word embeddings for candidates, and then find the words
that are most similar to the document itself. This method is highly effective
for quickly identifying key topics and concepts within text.
"""
# 提取关键词
# top_n: 返回关键词的数量
# diversity: 控制关键词的多样性，0表示不考虑多样性，1表示最大多样性
keywords = kw_model.extract_keywords(document, keyphrase_ngram_range=(1, 1), stop_words='english', top_n=5)
print("提取到的关键词：")
for keyword, score in keywords:
print(f"- {keyword}: {score:.4f}")
# 提取短语（ngram_range=(1, 2)表示提取单个词或两个词的短语）
keyphrases = kw_model.extract_keywords(document, keyphrase_ngram_range=(1, 2), stop_words='english', top_n=5)
print("\n提取到的关键词短语：")
for keyphrase, score in keyphrases:
print(f"- {keyphrase}: {score:.4f}")示例输出：
提取到的关键词： - keybert: 0.7303 - keyword: 0.6970 - bert: 0.6277 - extraction: 0.6033 - document: 0.5878 提取到的关键词短语： - keybert: 0.7303 - keyword extraction: 0.6970 - bert embeddings: 0.6277 - document embeddings: 0.5878 - cosine similarity: 0.5489
5. 注意事项
- 虚拟环境： 强烈建议在独立的Python虚拟环境（如venv或conda环境）中安装Python包。这有助于避免包冲突，并保持项目依赖的整洁。
- PATH环境变量： 如果在安装Rust后仍然遇到问题，请检查你的系统PATH环境变量是否正确包含了Cargo的bin目录。对于大多数操作系统，rustup会自动处理。在Linux/macOS上，通常是~/.cargo/bin。
- 系统代理/防火墙： 如果你所在的网络环境有严格的代理或防火墙设置，可能会影响curl命令或rustup下载组件。请确保网络连接正常，或配置相应的代理。
- Python版本兼容性： 尽管Rust依赖是主要问题，但始终建议使用KeyBERT官方文档推荐或兼容的Python版本。通常，Python 3.8及以上版本是安全的。
- IDE集成终端： 在VS Code等IDE的集成终端中安装时，如果遇到问题，尝试关闭IDE并重新打开，或者直接在系统原生终端中执行安装命令。有时IDE的环境变量刷新可能不及时。
6. 总结
KeyBERT是一个强大而灵活的关键词提取工具，但其安装过程有时会因Rust/Cargo的外部依赖而受阻。通过本教程，我们详细解释了安装失败的原因，并提供了通过rustup工具正确安装Rust和Cargo的步骤。解决这个核心依赖问题后，KeyBERT的安装将变得顺畅，你便可以充分利用其功能进行文本分析和关键词提取。理解并解决这类外部依赖问题是进行现代数据科学和机器学习项目时一项重要的技能。
