[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-nomic-ai--contrastors":3,"similar-nomic-ai--contrastors":111},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":17,"owner_company":18,"owner_location":18,"owner_email":19,"owner_twitter":20,"owner_website":21,"owner_url":22,"languages":23,"stars":36,"forks":37,"last_commit_at":38,"license":39,"difficulty_score":40,"env_os":41,"env_gpu":42,"env_ram":43,"env_deps":44,"category_tags":58,"github_topics":63,"view_count":75,"oss_zip_url":18,"oss_zip_packed_at":18,"status":76,"created_at":77,"updated_at":78,"faqs":79,"releases":110},7124,"nomic-ai\u002Fcontrastors","contrastors","Train Models Contrastively in Pytorch","contrastors 是一个专为高效训练和评估对比学习模型打造的 PyTorch 工具包。它主要解决了在资源受限环境下，难以快速训练大规模批次模型或处理长上下文嵌入的痛点，让研究人员和工程师能更轻松地复现前沿成果。\n\n该工具特别适合从事自然语言处理、计算机视觉的研究者，以及需要构建高质量文本或图像嵌入系统的开发者。其核心技术亮点在于深度集成了 Flash Attention，显著提升了训练速度与内存效率；同时支持 GradCache 技术，允许在显存有限的情况下使用超大批次进行训练。此外，contrastors 还原生支持 Huggingface 主流模型架构，并实现了独特的“套娃表示学习”（Matryoshka Representation Learning），让用户能灵活调整嵌入向量维度而不必重新训练。无论是进行掩码语言模型预训练，还是实施 CLIP、LiT 风格的对比学习，contrastors 都能提供稳定且高性能的支持，是探索下一代多模态与文本嵌入模型的理想助手。","# contrastors\n\n`contrastors` is contrastive learning toolkit that enables researchers and engineers to train and evaluate contrastive models efficiently.\n\n\n[![img](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnomic-ai_contrastors_readme_8908abd346f6.png)](https:\u002F\u002Fatlas.nomic.ai\u002Fmap\u002Fnomic-text-embed-v1-5m-sample)\n\n\n## Features\n\n- Built on top of [Flash Attention](https:\u002F\u002Fgithub.com\u002FDao-AILab\u002Fflash-attention) for fast and efficient training\n- Support for training on multiple GPUs\n- [GradCache](https:\u002F\u002Fgithub.com\u002Fluyug\u002FGradCache) support for training with large batch sizes in constrained memory environments\n- Huggingface Support for easy loading of common models (Pythia\u002FGPTNeoX, BERT, etc.)\n- Masked Language Modeling (MLM) Pretraining\n- [Matryoshka Representation Learning](https:\u002F\u002Farxiv.org\u002Fabs\u002F2205.13147) for flexible embedding sizes\n- [CLIP](https:\u002F\u002Farxiv.org\u002Fabs\u002F2103.00020) and [LiT](https:\u002F\u002Farxiv.org\u002Fabs\u002F2111.07991) style contrastive learning\n- Support for loading popular ViT (e.g. [timm](https:\u002F\u002Fhuggingface.co\u002Ftimm)) models\n\n## Research\n\n* [Nomic Embed: Training a Reproducible Long Context Text Embedder](https:\u002F\u002Farxiv.org\u002Fabs\u002F2402.01613) by Zach Nussbaum, Jack Morris, Andriy Mulyar, and Brandon Duderstadt\n* [Nomic Embed Vision: Expanding the Latent Space](https:\u002F\u002Farxiv.org\u002Fabs\u002F2406.18587) by Zach Nussbaum, Brandon Duderstadt, and Andriy Mulyar\n* [Training Sparse Mixture Of Experts Text Embedding Models](https:\u002F\u002Fstatic.nomic.ai\u002Fnomic_embed_multi_preprint.pdf) by Zach Nussbaum and Brandon Duderstadt \n\n## Getting Started and Requirements\n\nThe `contrastors` library relies on custom kernels from the [Flash Attention](https:\u002F\u002Fgithub.com\u002FDao-AILab\u002Fflash-attention) repository. To setup your enviornment you will need to follow the steps below.\n\nMake sure that you have Cuda 11.8+. You can check this by running `nvcc --version` or if you already have torch installed you can run `python -c \"import torch; print(torch.version.cuda)\"`\n\nCreate a python venv and activate it\n\n```bash\npython3 -m venv env\nsource env\u002Fbin\u002Factivate\n```\n\nInstall [torch](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F). See the torch docs for specific instructions for your system (e.g. the default CUDA torch supports is 12.1 as of 12\u002F12\u002F2023).\n\n```bash\npip3 install torch torchvision torchaudio\n```\n\nInstall wheel, packaging, ninja for Flash Attention (so the builds don't take too long)\n\n```bash\npip install wheel packaging ninja setuptools\n```\n\nInstall Flash Attention and the custom kernels\n\n```bash\npip install --no-cache-dir flash-attn --no-build-isolation git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Frotary git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Flayer_norm git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Ffused_dense_lib git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Fxentropy\n```\n\nInstall the rest of the requirements and the package\n\n```bash\npip install -e . \n```\n\n## Data Access\n\nWe provide access to the `nomic-embed-text-v1` dataset via the `nomic` package. To access the data, you will need to create an account and login to the `nomic` package. First create an account at [atlas.nomic.ai](https:\u002F\u002Fatlas.nomic.ai), download the `nomic` Python client, and run the following commands:\n\n```bash\npip install nomic\nnomic login # follow prompts to login\npython -c \"from nomic import atlas; print(atlas._get_datastream_credentials(name='contrastors'))\"\n```\n\nwhich will print out your access keys. You can then configure them by using `aws configure` or setting\nthe `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.\n\nIf you do not have the AWS CLI installed, you can install it [here](https:\u002F\u002Fdocs.aws.amazon.com\u002Fcli\u002Flatest\u002Fuserguide\u002Fgetting-started-install.html).\n\nTo verify your access, you can run the following command to list the contents of the bucket:\n\n```bash\naws s3 ls --endpoint-url=https:\u002F\u002F9fa58365a1a3d032127970d0bd9a1290.r2.cloudflarestorage.com\u002F s3:\u002F\u002Fcontrastive\naws s3 ls --endpoint-url=https:\u002F\u002F9fa58365a1a3d032127970d0bd9a1290.r2.cloudflarestorage.com\u002F s3:\u002F\u002Fcontrastive-index-filtered\n```\n\nYou should be able to see the contents of the bucket and download the data.\n\nIf you intend to train using our data and the `contrastors` repo, you will need to setup `fsspec` support for Cloudflare R2. To do so,\ncreate a file `~\u002F.config\u002Ffsspec\u002Fs3.json` with the following contents:\n\n```json\n{\n  \"s3\": {\n    \"client_kwargs\": {\n      \"endpoint_url\": \"https:\u002F\u002F9fa58365a1a3d032127970d0bd9a1290.r2.cloudflarestorage.com\u002F\",\n      \"aws_access_key_id\": \u003CACCESS_KEY_ID>,\n      \"aws_secret_access_key\": \u003CSECRET_KEY_ID>\n    }\n  }\n}\n```\n\n### Nomic Data Format\n\nOur text data is stored in gziped jsonl files with which we also store a `counts.json` file and `offsets.json.gzip`.\n\nThe `counts.json` file is a dictionary mapping the file name to the number of examples in the file. The `offsets.json.gz` file is a dictionary mapping the file name to a dictionary where each key is the index of the example and the value is a tuple of the start and end byte offset of the example in the file. We do this to allow for streaming of data in from R2, especially when the data is larger than the buffer size.\n\nHere's a small example of what a dataset configuration might look like:\n\n```yaml\ndatasets:\n  - name: \"paq\"\n    bucket: \"s3:\u002F\u002Fcontrastive-index-filtered\u002Fpaq_full\u002Fshard-{00000..00538}.jsonl.gz\"\n    query_prefix: \"search_query\"\n    document_prefix: \"search_document\"\n    objective: \n        type: \"paired\"\n        columns: [\"query\", \"document\"]\n\n```\n\n`objective` defines if it's a paired or triplet objective. In both cases, the `columns` field defines the columns to use for each example.\n\n## Training `nomic-embed-text-v1`\n\n### Masked Language Modeling Pretraining\n\nTo train your own BERT from scratch (with all the optimizations) run\n\n```bash\ncd src\u002Fcontrastors\ndeepspeed --num_gpus=8 train.py --config=configs\u002Ftrain\u002Fmlm.yaml --deepspeed_config=configs\u002Fdeepspeed\u002Fds_config.json --dtype=bf16\n```\n\n### Constrastive Pretraining and Finetuning\n\nTo launch an experiment run\n\n```bash\ncd src\u002Fcontrastors\ntorchrun --nproc-per-node=8 train.py --config=configs\u002Ftrain\u002Fcontrastive_pretrain.yaml --dtype=bf16\n```\n\nThis will train a bert model on all ~200M examples. To change the dataset, you can modify `data_args.input_shards`.\n\nTo finetune `nomic-bert-embed-v1-unsupervised`, update the config to `configs\u002Ftrain\u002Fcontrastive_finetune.yaml`.\n\n### Generating Your Own Data\n\nTo generate your own data for any step of the pipeline, you can use the provided scripts in `scripts\u002Ftext`. \n\nSee the [README](scripts\u002Ftext\u002FREADME.md) in `scripts\u002Ftext` for more information.\n\n\n\n## Training `nomic-embed-vision-v1.5`\n\nTo align a vision model, you will need to curate a large image-text dataset. More details can be found [here](https:\u002F\u002Fgithub.com\u002From1504\u002Fimg2dataset).\n\nTo align `nomic-embed-vision-v1.5` with `nomic-embed-text-v1.5`, you can run the following command:\n\n```bash\ndeepspeed  train.py --deepspeed_config=configs\u002Fdeepspeed\u002Fimage_text.json --config=configs\u002Ftrain\u002Fnomic_embed_vision_v1.5.yaml --dtype=bf16\n```\n\n## Pretrained Models\n\nWe provide pretrained models for `Nomic Embed` at the following locations:\n\n- [nomic-embed-text-v2-moe](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v2-moe)\n- [nomic-embed-text-v2-moe-unsupervised](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v2-moe-unsupervised)\n- [nomic-embed-text-v1](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1)\n- [nomic-embed-vision-v1](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-vision-v1)\n- [nomic-embed-text-v1.5](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1.5)\n- [nomic-embed-vision-v1.5](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-vision-v1.5)\n- [nomic-embed-text-v1-ablated](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1-ablated)\n- [nomic-embed-text-v1-unsupervised](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1-unsupervised)\n- [nomic-bert-2048](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-bert-2048)\n- [nomic-xlm-2048](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-xlm-2048)\n\n## Join the Nomic Community\n\n- Nomic: [https:\u002F\u002Fnomic.ai](https:\u002F\u002Fnomic.ai)\n- Discord: [https:\u002F\u002Fdiscord.gg\u002FmyY5YDR8z8](https:\u002F\u002Fdiscord.gg\u002FmyY5YDR8z8)\n- Twitter: [https:\u002F\u002Ftwitter.com\u002Fnomic_ai](https:\u002F\u002Ftwitter.com\u002Fnomic_ai)\n\n## License\n\nThis code is licensed under the [Apache 2.0 License](LICENSE). See the model cards for the individual license for each model. \n\n## Acknowledgements\n\nWe thank Tri Dao for his work on Flash Attention and the custom kernels that make this project possible, the [OpenCLIP](https:\u002F\u002Fgithub.com\u002Fmlfoundations\u002Fopen_clip) team for their\ngreat repository with which much of this work is based on, and the Huggingface team for their great work on the transformers library.\n\n\n## Citation\n\nIf you find the model, dataset, or training code useful, please cite our work\n\n```bibtex\n@misc{nussbaum2024nomic,\n      title={Nomic Embed: Training a Reproducible Long Context Text Embedder}, \n      author={Zach Nussbaum and John X. Morris and Brandon Duderstadt and Andriy Mulyar},\n      year={2024},\n      eprint={2402.01613},\n      archivePrefix={arXiv},\n      primaryClass={cs.CL}\n}\n@misc{nussbaum2024nomicembedvisionexpanding,\n      title={Nomic Embed Vision: Expanding the Latent Space}, \n      author={Zach Nussbaum and Brandon Duderstadt and Andriy Mulyar},\n      year={2024},\n      eprint={2406.18587},\n      archivePrefix={arXiv},\n      primaryClass={cs.CV},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2406.18587}, \n}\n@misc{nussbaum2025trainingsparsemixtureexperts,\n      title={Training Sparse Mixture Of Experts Text Embedding Models}, \n      author={Zach Nussbaum and Brandon Duderstadt},\n      year={2025},\n      eprint={2502.07972},\n      archivePrefix={arXiv},\n      primaryClass={cs.CL},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2502.07972}, \n}\n```\n","# 对比学习工具包\n\n`contrastors` 是一个对比学习工具包，使研究人员和工程师能够高效地训练和评估对比模型。\n\n\n[![img](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnomic-ai_contrastors_readme_8908abd346f6.png)](https:\u002F\u002Fatlas.nomic.ai\u002Fmap\u002Fnomic-text-embed-v1-5m-sample)\n\n\n## 特性\n\n- 基于 [Flash Attention](https:\u002F\u002Fgithub.com\u002FDao-AILab\u002Fflash-attention) 构建，实现快速高效的训练\n- 支持多 GPU 训练\n- [GradCache](https:\u002F\u002Fgithub.com\u002Fluyug\u002FGradCache) 支持，在内存受限的环境中使用大批次进行训练\n- Huggingface 支持，方便加载常用模型（Pythia\u002FGPTNeoX、BERT 等）\n- 掩码语言模型（MLM）预训练\n- [套娃表示学习](https:\u002F\u002Farxiv.org\u002Fabs\u002F2205.13147)，支持灵活的嵌入尺寸\n- [CLIP](https:\u002F\u002Farxiv.org\u002Fabs\u002F2103.00020) 和 [LiT](https:\u002F\u002Farxiv.org\u002Fabs\u002F2111.07991) 风格的对比学习\n- 支持加载流行的 ViT 模型（例如 [timm](https:\u002F\u002Fhuggingface.co\u002Ftimm)）\n\n## 研究成果\n\n* [Nomic Embed：训练可复现的长上下文文本嵌入模型](https:\u002F\u002Farxiv.org\u002Fabs\u002F2402.01613) 由 Zach Nussbaum、Jack Morris、Andriy Mulyar 和 Brandon Duderstadt 共同撰写\n* [Nomic Embed Vision：扩展潜在空间](https:\u002F\u002Farxiv.org\u002Fabs\u002F2406.18587) 由 Zach Nussbaum、Brandon Duderstadt 和 Andriy Mulyar 共同撰写\n* [训练稀疏专家混合文本嵌入模型](https:\u002F\u002Fstatic.nomic.ai\u002Fnomic_embed_multi_preprint.pdf) 由 Zach Nussbaum 和 Brandon Duderstadt 共同撰写\n\n## 快速入门与环境要求\n\n`contrastors` 库依赖于 [Flash Attention](https:\u002F\u002Fgithub.com\u002FDao-AILab\u002Fflash-attention) 仓库中的自定义内核。要设置您的环境，请按照以下步骤操作。\n\n请确保您已安装 CUDA 11.8 或更高版本。您可以通过运行 `nvcc --version` 来检查，或者如果您已经安装了 PyTorch，可以运行 `python -c \"import torch; print(torch.version.cuda)\"`。\n\n创建并激活 Python 虚拟环境：\n\n```bash\npython3 -m venv env\nsource env\u002Fbin\u002Factivate\n```\n\n安装 [PyTorch](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F)。请参阅 PyTorch 文档，获取适用于您系统的具体安装说明（例如，截至 2023 年 12 月 12 日，默认支持的 CUDA 版本为 12.1）。\n\n```bash\npip3 install torch torchvision torchaudio\n```\n\n安装 wheel、packaging 和 ninja，以加速 Flash Attention 的构建过程：\n\n```bash\npip install wheel packaging ninja setuptools\n```\n\n安装 Flash Attention 及其自定义内核：\n\n```bash\npip install --no-cache-dir flash-attn --no-build-isolation git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Frotary git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Flayer_norm git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Ffused_dense_lib git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Fxentropy\n```\n\n安装其余依赖项及该包：\n\n```bash\npip install -e .\n```\n\n## 数据访问\n\n我们通过 `nomic` 包提供对 `nomic-embed-text-v1` 数据集的访问权限。要访问数据，您需要先在 [atlas.nomic.ai](https:\u002F\u002Fatlas.nomic.ai) 上注册账号并登录 `nomic` 包。首先下载 `nomic` Python 客户端，并运行以下命令：\n\n```bash\npip install nomic\nnomic login # 按照提示登录\npython -c \"from nomic import atlas; print(atlas._get_datastream_credentials(name='contrastors'))\"\n```\n\n这将打印出您的访问密钥。您可以使用 `aws configure` 或设置 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 环境变量来配置这些密钥。\n\n如果您尚未安装 AWS CLI，可以从 [这里](https:\u002F\u002Fdocs.aws.amazon.com\u002Fcli\u002Flatest\u002Fuserguide\u002Fgetting-started-install.html) 下载。\n\n要验证您的访问权限，可以运行以下命令列出存储桶内容：\n\n```bash\naws s3 ls --endpoint-url=https:\u002F\u002F9fa58365a1a3d032127970d0bd9a1290.r2.cloudflarestorage.com\u002F s3:\u002F\u002Fcontrastive\naws s3 ls --endpoint-url=https:\u002F\u002F9fa58365a1a3d032127970d0bd9a1290.r2.cloudflarestorage.com\u002F s3:\u002F\u002Fcontrastive-index-filtered\n```\n\n您应该能够看到存储桶中的内容并下载数据。\n\n如果您打算使用我们的数据和 `contrastors` 仓库进行训练，还需要为 Cloudflare R2 设置 `fsspec` 支持。为此，创建文件 `~\u002F.config\u002Ffsspec\u002Fs3.json`，内容如下：\n\n```json\n{\n  \"s3\": {\n    \"client_kwargs\": {\n      \"endpoint_url\": \"https:\u002F\u002F9fa58365a1a3d032127970d0bd9a1290.r2.cloudflarestorage.com\u002F\",\n      \"aws_access_key_id\": \u003CACCESS_KEY_ID>,\n      \"aws_secret_access_key\": \u003CSECRET_KEY_ID>\n    }\n  }\n}\n```\n\n### Nomic 数据格式\n\n我们的文本数据存储在 gzip 压缩的 jsonl 文件中，同时附带 `counts.json` 文件和 `offsets.json.gz` 文件。\n\n`counts.json` 文件是一个字典，将文件名映射到该文件中的样本数量。`offsets.json.gz` 文件也是一个字典，将文件名映射到另一个字典，其中每个键是样本的索引，值则是该样本在文件中开始和结束的字节偏移量。这样做是为了支持从 R2 流式传输数据，尤其是在数据量超过缓冲区大小时。\n\n以下是一个小型的数据集配置示例：\n\n```yaml\ndatasets:\n  - name: \"paq\"\n    bucket: \"s3:\u002F\u002Fcontrastive-index-filtered\u002Fpaq_full\u002Fshard-{00000..00538}.jsonl.gz\"\n    query_prefix: \"search_query\"\n    document_prefix: \"search_document\"\n    objective: \n        type: \"paired\"\n        columns: [\"query\", \"document\"]\n\n```\n\n`objective` 定义是成对还是三元组目标。在两种情况下，`columns` 字段都定义了每个样本所使用的列。\n\n## 训练 `nomic-embed-text-v1`\n\n### 掩码语言模型预训练\n\n要从头开始训练您自己的 BERT 模型（包含所有优化），请运行：\n\n```bash\ncd src\u002Fcontrastors\ndeepspeed --num_gpus=8 train.py --config=configs\u002Ftrain\u002Fmlm.yaml --deepspeed_config=configs\u002Fdeepspeed\u002Fds_config.json --dtype=bf16\n```\n\n### 对比预训练与微调\n\n要启动实验，请运行：\n\n```bash\ncd src\u002Fcontrastors\ntorchrun --nproc-per-node=8 train.py --config=configs\u002Ftrain\u002Fcontrastive_pretrain.yaml --dtype=bf16\n```\n\n这将基于全部约 2 亿个样本训练一个 BERT 模型。如需更改数据集，可以修改 `data_args.input_shards`。\n\n要微调 `nomic-bert-embed-v1-unsupervised`，请将配置更新为 `configs\u002Ftrain\u002Fcontrastive_finetune.yaml`。\n\n### 生成您自己的数据\n\n要为流程中的任何步骤生成您自己的数据，可以使用 `scripts\u002Ftext` 中提供的脚本。\n\n更多信息请参阅 `scripts\u002Ftext` 中的 [README](scripts\u002Ftext\u002FREADME.md)。\n\n## 训练 `nomic-embed-vision-v1.5`\n\n要对齐视觉模型，您需要整理一个大型的图像-文本数据集。更多详细信息请参见 [这里](https:\u002F\u002Fgithub.com\u002From1504\u002Fimg2dataset)。\n\n要将 `nomic-embed-vision-v1.5` 与 `nomic-embed-text-v1.5` 对齐，可以运行以下命令：\n\n```bash\ndeepspeed  train.py --deepspeed_config=configs\u002Fdeepspeed\u002Fimage_text.json --config=configs\u002Ftrain\u002Fnomic_embed_vision_v1.5.yaml --dtype=bf16\n```\n\n## 预训练模型\n\n我们在以下位置提供了 `Nomic Embed` 的预训练模型：\n\n- [nomic-embed-text-v2-moe](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v2-moe)\n- [nomic-embed-text-v2-moe-unsupervised](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v2-moe-unsupervised)\n- [nomic-embed-text-v1](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1)\n- [nomic-embed-vision-v1](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-vision-v1)\n- [nomic-embed-text-v1.5](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1.5)\n- [nomic-embed-vision-v1.5](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-vision-v1.5)\n- [nomic-embed-text-v1-ablated](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1-ablated)\n- [nomic-embed-text-v1-unsupervised](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-embed-text-v1-unsupervised)\n- [nomic-bert-2048](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-bert-2048)\n- [nomic-xlm-2048](https:\u002F\u002Fhuggingface.co\u002Fnomic-ai\u002Fnomic-xlm-2048)\n\n## 加入 Nomic 社区\n\n- Nomic: [https:\u002F\u002Fnomic.ai](https:\u002F\u002Fnomic.ai)\n- Discord: [https:\u002F\u002Fdiscord.gg\u002FmyY5YDR8z8](https:\u002F\u002Fdiscord.gg\u002FmyY5YDR8z8)\n- Twitter: [https:\u002F\u002Ftwitter.com\u002Fnomic_ai](https:\u002F\u002Ftwitter.com\u002Fnomic_ai)\n\n## 许可证\n\n本代码采用 [Apache 2.0 许可证](LICENSE)授权。各模型的具体许可证信息请参阅相应的模型卡片。\n\n## 致谢\n\n我们感谢 Tri Dao 在 Flash Attention 和自定义内核方面的工作，正是这些技术使本项目得以实现；感谢 [OpenCLIP](https:\u002F\u002Fgithub.com\u002Fmlfoundations\u002Fopen_clip) 团队提供的优秀仓库，我们的许多工作都基于此；同时也感谢 Hugging Face 团队在 Transformers 库方面的杰出贡献。\n\n## 引用\n\n如果您认为该模型、数据集或训练代码有用，请引用我们的工作：\n\n```bibtex\n@misc{nussbaum2024nomic,\n      title={Nomic Embed: 训练可复现的长上下文文本嵌入模型}, \n      author={Zach Nussbaum、John X. Morris、Brandon Duderstadt 和 Andriy Mulyar},\n      year={2024},\n      eprint={2402.01613},\n      archivePrefix={arXiv},\n      primaryClass={cs.CL}\n}\n@misc{nussbaum2024nomicembedvisionexpanding,\n      title={Nomic Embed Vision: 扩展潜在空间}, \n      author={Zach Nussbaum、Brandon Duderstadt 和 Andriy Mulyar},\n      year={2024},\n      eprint={2406.18587},\n      archivePrefix={arXiv},\n      primaryClass={cs.CV},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2406.18587}, \n}\n@misc{nussbaum2025trainingsparsemixtureexperts,\n      title={训练稀疏专家混合文本嵌入模型}, \n      author={Zach Nussbaum 和 Brandon Duderstadt},\n      year={2025},\n      eprint={2502.07972},\n      archivePrefix={arXiv},\n      primaryClass={cs.CL},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2502.07972}, \n}\n```","# Contrastors 快速上手指南\n\n`contrastors` 是一个基于 Flash Attention 构建的高效对比学习工具包，专为研究人员和工程师设计，支持大规模文本和视觉嵌入模型的训练与评估。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**: Linux (推荐)\n*   **GPU**: NVIDIA GPU (支持多卡训练)\n*   **CUDA**: 版本需为 11.8 或更高\n    *   检查命令：`nvcc --version` 或 `python -c \"import torch; print(torch.version.cuda)\"`\n*   **Python**: 建议 Python 3.8+\n*   **编译器**: 需安装 `ninja` 以加速编译过程\n\n> **注意**：由于该库依赖自定义 CUDA 内核，Windows 用户可能需要通过 WSL2 运行或自行解决编译环境问题。\n\n## 安装步骤\n\n请严格按照以下顺序执行命令，以确保依赖项正确编译和链接。\n\n### 1. 创建并激活虚拟环境\n\n```bash\npython3 -m venv env\nsource env\u002Fbin\u002Factivate\n```\n\n### 2. 安装 PyTorch\n\n根据您的 CUDA 版本安装对应的 PyTorch。以下为通用安装命令（具体版本请参考 [PyTorch 官网](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F)）：\n\n```bash\npip3 install torch torchvision torchaudio\n```\n\n### 3. 安装构建工具\n\n安装 `wheel`, `packaging`, `ninja` 等工具以加速 Flash Attention 的编译：\n\n```bash\npip install wheel packaging ninja setuptools\n```\n\n### 4. 安装 Flash Attention 及自定义内核\n\n这是最关键的一步，需要安装主库以及特定的子模块（rotary, layer_norm 等）：\n\n```bash\npip install --no-cache-dir flash-attn --no-build-isolation git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Frotary git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Flayer_norm git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Ffused_dense_lib git+https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fflash-attention.git#subdirectory=csrc\u002Fxentropy\n```\n\n### 5. 安装 Contrastors\n\n克隆仓库并安装本地包：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fnomic-ai\u002Fcontrastors.git\ncd contrastors\npip install -e .\n```\n\n## 基本使用\n\n### 数据访问配置（可选）\n\n如果您需要使用 Nomic 提供的预处理数据集（如 `nomic-embed-text-v1`），需配置 AWS S3 兼容凭证以访问 Cloudflare R2 存储桶。\n\n1.  安装 nomic 客户端并登录获取密钥：\n    ```bash\n    pip install nomic\n    nomic login\n    python -c \"from nomic import atlas; print(atlas._get_datastream_credentials(name='contrastors'))\"\n    ```\n2.  配置 `fsspec`：创建文件 `~\u002F.config\u002Ffsspec\u002Fs3.json` 并填入上一步获取的密钥：\n    ```json\n    {\n      \"s3\": {\n        \"client_kwargs\": {\n          \"endpoint_url\": \"https:\u002F\u002F9fa58365a1a3d032127970d0bd9a1290.r2.cloudflarestorage.com\u002F\",\n          \"aws_access_key_id\": \"\u003CYOUR_ACCESS_KEY_ID>\",\n          \"aws_secret_access_key\": \"\u003CYOUR_SECRET_ACCESS_KEY>\"\n        }\n      }\n    }\n    ```\n\n### 训练示例\n\n#### 1. 掩码语言建模 (MLM) 预训练\n从头训练一个优化的 BERT 模型（示例使用 8 张 GPU 和 bf16 精度）：\n\n```bash\ncd src\u002Fcontrastors\ndeepspeed --num_gpus=8 train.py --config=configs\u002Ftrain\u002Fmlm.yaml --deepspeed_config=configs\u002Fdeepspeed\u002Fds_config.json --dtype=bf16\n```\n\n#### 2. 对比学习预训练\n启动对比学习实验（支持 GradCache 以大批次训练）：\n\n```bash\ncd src\u002Fcontrastors\ntorchrun --nproc-per-node=8 train.py --config=configs\u002Ftrain\u002Fcontrastive_pretrain.yaml --dtype=bf16\n```\n\n*   **修改数据集**：编辑配置文件中的 `data_args.input_shards` 字段。\n*   **微调模型**：将 `--config` 参数更改为 `configs\u002Ftrain\u002Fcontrastive_finetune.yaml` 即可进行微调。\n\n#### 3. 视觉 - 文本对齐训练\n训练视觉嵌入模型（如 `nomic-embed-vision-v1.5`）：\n\n```bash\ndeepspeed train.py --deepspeed_config=configs\u002Fdeepspeed\u002Fimage_text.json --config=configs\u002Ftrain\u002Fnomic_embed_vision_v1.5.yaml --dtype=bf16\n```\n\n### 加载预训练模型\n\n您可以直接从 Hugging Face 加载已训练好的模型进行推理或进一步微调：\n\n*   **文本模型**: `nomic-ai\u002Fnomic-embed-text-v1.5`, `nomic-ai\u002Fnomic-embed-text-v2-moe`\n*   **视觉模型**: `nomic-ai\u002Fnomic-embed-vision-v1.5`\n*   **基础模型**: `nomic-ai\u002Fnomic-bert-2048`\n\n使用 Hugging Face `transformers` 库即可正常加载这些模型。","某 AI 初创团队正在构建一个支持长文档检索的企业级知识库，需要训练一个能精准捕捉语义细微差别的文本嵌入模型。\n\n### 没有 contrastors 时\n- **显存瓶颈限制批量大小**：受限于 GPU 显存，无法使用对比学习所需的大批量（Large Batch）数据，导致模型收敛慢且表征能力不足。\n- **训练速度缓慢**：缺乏针对注意力机制的底层优化，处理长上下文文本时计算开销巨大，单次实验周期长达数天。\n- **架构调整困难**：若想尝试如 Matryoshka（套娃式）可变长度嵌入或稀疏专家混合（MoE）等先进结构，需从零重写大量底层代码，研发风险高。\n- **多卡协同复杂**：在多 GPU 环境下手动配置分布式训练和数据并行策略繁琐，容易出错且资源利用率低。\n\n### 使用 contrastors 后\n- **突破显存限制**：利用内置的 GradCache 技术，在有限显存下成功实现大批量训练，显著提升了嵌入模型的区分度和泛化能力。\n- **极速训练体验**：基于 Flash Attention 定制内核，长文本训练速度提升数倍，将原本数天的迭代周期缩短至数小时。\n- **灵活架构即插即用**：直接调用对 Matryoshka 表示学习和 MoE 架构的原生支持，轻松部署可动态调整维度的高效模型，无需重复造轮子。\n- **开箱即用的分布式支持**：原生支持多 GPU 并行训练，配合 HuggingFace 模型加载接口，快速复现 Nomic Embed 等前沿论文效果。\n\ncontrastors 通过底层算子优化与高级训练策略的封装，让研发团队能以最低成本高效产出工业级长文本嵌入模型。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnomic-ai_contrastors_d4332b8d.png","nomic-ai","Nomic AI","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fnomic-ai_4d77c6c8.png","democratizing access to powerful artificial intelligence",null,"work@nomic.ai","nomic_ai","https:\u002F\u002Fnomic.ai","https:\u002F\u002Fgithub.com\u002Fnomic-ai",[24,28,32],{"name":25,"color":26,"percentage":27},"Python","#3572A5",99.1,{"name":29,"color":30,"percentage":31},"Shell","#89e051",0.9,{"name":33,"color":34,"percentage":35},"Makefile","#427819",0,783,67,"2026-04-12T16:28:57","Apache-2.0",4,"Linux","必需 NVIDIA GPU，支持 CUDA 11.8+（推荐），需安装 Flash Attention 及其自定义内核；支持多 GPU 训练","未说明（但在受限显存环境下支持通过 GradCache 进行大批次训练）",{"notes":45,"python":46,"dependencies":47},"1. 必须手动安装特定版本的 Flash Attention 及多个自定义内核组件（rotary, layer_norm, fused_dense_lib, xentropy）。2. 访问官方数据集需注册 Nomic 账号并配置 AWS CLI 或环境变量以连接 Cloudflare R2 存储。3. 训练脚本依赖 DeepSpeed 或 torchrun 进行分布式启动。4. 默认数据类型建议使用 bf16。5. 未明确提及对 macOS 或 Windows 的支持，鉴于 Flash Attention 的编译要求，主要面向 Linux 环境。","3.x (通过 python3 -m venv 创建环境，具体小版本未说明)",[48,49,50,51,52,53,54,55,56,57],"torch","torchvision","torchaudio","flash-attn","transformers (隐含，支持 Huggingface 模型)","deepspeed","nomic","fsspec","wheel","ninja",[59,60,61,62],"语言模型","图像","其他","开发框架",[64,65,66,67,68,69,70,71,72,73,74],"contrastive-learning","deep-learning","embeddings","pytorch","text-embeddings","dense-retrieval","transformers","image-embeddings","multimodal","multimodal-rag","rag",2,"ready","2026-03-27T02:49:30.150509","2026-04-13T22:46:02.311117",[80,85,90,95,100,105],{"id":81,"question_zh":82,"answer_zh":83,"source_url":84},32020,"访问训练数据集时出现 'Access Denied' 错误怎么办？","这通常是由于 AWS 凭证配置不正确导致的。请确保您已使用正确的密钥运行了 `aws configure`。您可以尝试通过以下 Python 命令获取数据流凭证：\n`python -c \"from nomic import atlas; print(atlas._get_datastream_credentials(name='contrastors'))\"`\n然后使用这些密钥重新配置 AWS。如果问题仍然存在，可能是存储桶权限有所变更，建议关注官方更新或等待数据镜像到 Hugging Face。","https:\u002F\u002Fgithub.com\u002Fnomic-ai\u002Fcontrastors\u002Fissues\u002F79",{"id":86,"question_zh":87,"answer_zh":88,"source_url":89},32021,"安装 FAISS 时遇到 'make: *** build: No such file or directory' 错误如何解决？","该错误通常是因为当前目录不正确。请尝试先切换到 cmake 目录重新运行 cmake，然后再进入 faiss 目录构建。具体步骤如下：\n1. 进入 cmake 目录（例如 `\u002Fopt\u002Fdlami\u002Fnvme\u002Ffaiss\u002Fcmake-3.28.0-rc4`）并运行 cmake。\n2. 返回 faiss 根目录或确保在正确路径下，再次运行 `make -C build -j faiss`。\n确保构建目录 `build` 已正确生成。","https:\u002F\u002Fgithub.com\u002Fnomic-ai\u002Fcontrastors\u002Fissues\u002F52",{"id":91,"question_zh":92,"answer_zh":93,"source_url":94},32022,"多语言对比预训练数据在哪里可以找到？README 中的链接无法访问。","README 中列出的部分存储桶包含的是早期实验数据，并非最终训练使用的数据。您应该使用配置文件 `contrastive_pretrain_multilingual_full.yaml`。实际训练使用的数据是 `mc4-filtered` 而不是 `mc4`。请确保您的 AWS 配置正确，并尝试访问 `s3:\u002F\u002Fcontrastive-index-filtered` 或相关过滤后的数据集路径。","https:\u002F\u002Fgithub.com\u002Fnomic-ai\u002Fcontrastors\u002Fissues\u002F78",{"id":96,"question_zh":97,"answer_zh":98,"source_url":99},32023,"使用默认配置进行对比预训练时显存不足（OOM）怎么办？","如果遇到显存不足，可以尝试减小序列长度（sequence length）或块大小（chunk size）。维护者建议：预训练时保留序列长度为 2048，微调时使用 512。虽然减小块大小可能会降低训练速度，但不会影响模型性能。此外，减小 batch size 也是一种有效的临时解决方案。","https:\u002F\u002Fgithub.com\u002Fnomic-ai\u002Fcontrastors\u002Fissues\u002F47",{"id":101,"question_zh":102,"answer_zh":103,"source_url":104},32024,"对比微调训练在完成第一个 epoch 后停止，没有报错也没有继续训练，是什么原因？","这是一个已知的 Bug，已在提交 `9089049` 中修复。如果您遇到训练在第一个 epoch 结束后立即停止且后续 epoch 进度为 0% 的情况，请拉取最新的代码更新。该问题表现为 MTEB 结果在第一个和最后一个 epoch 完全相同，更新代码后即可解决。","https:\u002F\u002Fgithub.com\u002Fnomic-ai\u002Fcontrastors\u002Fissues\u002F44",{"id":106,"question_zh":107,"answer_zh":108,"source_url":109},32025,"如何在非英语（多语言）任务上评估模型效果？Tokenizer 对非罗曼语系支持不好怎么办？","BERT 类模型的 tokenizer 对非罗曼语系（如印地语等）的支持可能较差，导致掩码填充（mask filling）等定性检查结果不理想。官方主要通过 GLUE 基准来衡量模型质量。如果您发现特定语言效果不佳，可能是 tokenizer 未能很好地表示该语言词汇，或者是数据\u002F超参数问题。建议检查 tokenizer 的词表覆盖情况，或考虑针对特定语言进行额外的微调。","https:\u002F\u002Fgithub.com\u002Fnomic-ai\u002Fcontrastors\u002Fissues\u002F32",[],[112,123,131,139,147,156],{"id":113,"name":114,"github_repo":115,"description_zh":116,"stars":117,"difficulty_score":118,"last_commit_at":119,"category_tags":120,"status":76},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[121,62,60,122],"Agent","数据工具",{"id":124,"name":125,"github_repo":126,"description_zh":127,"stars":128,"difficulty_score":118,"last_commit_at":129,"category_tags":130,"status":76},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[62,60,121],{"id":132,"name":133,"github_repo":134,"description_zh":135,"stars":136,"difficulty_score":75,"last_commit_at":137,"category_tags":138,"status":76},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",153609,"2026-04-13T11:34:59",[62,121,59],{"id":140,"name":141,"github_repo":142,"description_zh":143,"stars":144,"difficulty_score":75,"last_commit_at":145,"category_tags":146,"status":76},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[62,60,121],{"id":148,"name":149,"github_repo":150,"description_zh":151,"stars":152,"difficulty_score":75,"last_commit_at":153,"category_tags":154,"status":76},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[155,121,60,62],"插件",{"id":157,"name":158,"github_repo":159,"description_zh":160,"stars":161,"difficulty_score":75,"last_commit_at":162,"category_tags":163,"status":76},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[155,62]]