mlx-embed-finetune：在 Apple Silicon 上用 MLX 微调单向量嵌入模型

核心能力与快速开始

★ 3 · Python

能做什么

在 Apple Silicon 上用 MLX 微调单向量嵌入模型：训练 LoRA/QLoRA 适配器；按模块路径匹配注意力投影以覆盖编码器与解码器风格模型族；对比批次内池化显式硬负样本并保护已知正样本；通过 --multi-positive 对全部已知相关答案做多正样本监督并去重候选；通过 --cache-chunk-size 限定编码/回放分块、配合 --batch-size 设置共享对比池实现 GradCache 梯度缓存；由 teacher.py 保存教师分数，再用 --teacher-scores 与 --distill-weight 在不加载教师的情况下做学生蒸馏；支持 Matryoshka 损失以训练选定嵌入前缀并评估维度/质量权衡；支持基于难度的负样本加权；按验证损失、nDCG@10、MRR@10 或 Recall@10 选择检查点并在导出前恢复；提供分块精确打分的语料评测，含多相关文档、二值 nDCG@10、Recall@k 与 MRR@10；支持将适配器合并导出为 MLX 权重格式，QLoRA 融合会反量化适配层而其他层可保持量化。

适用场景

在 Mac（Apple Silicon）本地对检索用单向量嵌入模型做参数高效微调；针对自有查询-文档对数据训练并挑选检查点后导出合并权重，用于本地语义搜索；用教师模型排序分数做离线蒸馏以提升学生嵌入模型的检索排序；在受显存/内存限制时借助 GradCache 扩大对比学习批次；对嵌入维度做 Matryoshka 截断并评估维度与检索质量的取舍；在 SciFact 等语料式评测中复现 nDCG@10、Recall@k、MRR@10 指标并做公平对比。

项目形态

开发框架

部署方式

README 说明本地在 Apple Silicon 原生 Python 环境中运行（git clone + venv + pip install -r requirements.txt，随后执行 train.py / evaluate.py）；模型权重首次使用时下载；导出结果为 MLX 权重格式。未说明云端或其他平台的部署方式。

主要依赖

需 Apple Silicon 原生 Python 环境，记录使用的配置为 Python 3.12 与 3.14（详见 docs/validation.md）；依赖见 requirements.txt；构建于 MLX、mlx-lm、mlx-embeddings 之上。未说明具体内存、GPU 或成本等要求。

使用限制

已实现路径仅支持每个文本输入对应一个嵌入向量。GradCache 需要无状态编码器前向（MLX 随机性除外），且不支持 BatchNorm 模型。保存的适配器检查点不支持精确的优化器/RNG 续训。合并导出使用 MLX 权重格式，Transformers 与 GGUF 转换需另行验证；QLoRA 融合会反量化适配层。服务时需匹配检查点的查询/文档提示与归一化；更改嵌入权重通常需要重新嵌入语料，即使输出维度与服务 API 不变。README 指出附带示例仅用于验证执行，其容易的检索分数并不代表微调带来提升；特定训练配方是否提升检索质量需要留出集消融实验。许可证为 Apache-2.0（仅指本仓库代码），基础模型与数据集各自保留其许可证。

许可证

Apache-2.0

最近推送

2026-10-12 10:25

资料检查：2026-10-13 07:00 · 卡片整理：2026-10-13 07:00
卡片由 AI 根据仓库资料整理，未进行安装或运行验证