[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-qdrant--quaterion":3,"tool-qdrant--quaterion":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},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",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},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",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},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 真正成长为懂上",148568,2,"2026-04-09T23:34:24",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},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 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108111,"2026-04-08T11:23:26",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},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",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},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",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":77,"owner_twitter":78,"owner_website":79,"owner_url":80,"languages":81,"stars":86,"forks":87,"last_commit_at":88,"license":89,"difficulty_score":32,"env_os":90,"env_gpu":91,"env_ram":90,"env_deps":92,"category_tags":97,"github_topics":98,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":111,"updated_at":112,"faqs":113,"releases":144},5597,"qdrant\u002Fquaterion","quaterion","Blazing fast framework for fine-tuning similarity learning models","Quaterion 是一个专为微调相似度学习模型打造的高性能框架，旨在解决语义搜索、推荐系统、异常检测等任务中模型训练的“最后一公里”难题。它巧妙结合了预训练模型的强大能力与特定任务的定制化需求，让用户无需经历漫长且昂贵的全量训练过程，即可快速获得专用模型。\n\n这款工具特别适合需要处理小数据集的开发者与研究人员。即使只有少量标注数据（例如一天内可完成标注的量），Quaterion 也能通过其专门设计的头部网络层发挥预训练模型的优势。其最独特的技术亮点在于内置的高速缓存机制，这使得在普通笔记本电脑的 GPU 上也能以极大的批量大小进行数千轮次的快速训练，显著降低了硬件门槛。此外，Quaterion 基于 PyTorch Lightning 构建，继承了其优秀的可扩展性与可靠性，同时支持灵活定制训练流程的各个部分。为了方便部署，它还提供了独立的轻量级推理包，避免在生产环境中安装沉重的训练依赖。无论是想快速验证想法的算法工程师，还是希望优化现有搜索匹配效果的技术团队，Quaterion 都能提供高效、灵活的解决方案。","\u003Cp align=\"center\">\n  \u003Cimg height=\"100\" src=\"docs\u002Fimgs\u002Flogo.svg\" alt=\"Quaterion\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n    \u003Cb>Blazing fast framework for fine-tuning Similarity Learning models\u003C\u002Fb>\n\u003C\u002Fp>\n\n\u003Cp align=center>\n    \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fquaterion\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fquaterion?label=pypi\" alt=\"Version\" \u002F>\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Factions\u002Fworkflows\u002Ftest.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg\" alt=\"Tests status\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fqdrant.to\u002Fdiscord\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Qdrant-5865F2.svg?logo=discord\" alt=\"Discord\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fquaterion.qdrant.tech\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLearn-Docs%20%26%20Tutorials-success\" alt=\"Docs & Tutorials\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n>  A dwarf on a giant's shoulders sees farther of the two\n\nQuaterion is a framework for fine-tuning similarity learning models.\nThe framework closes the \"last mile\" problem in training models for semantic search, recommendations, anomaly detection, extreme classification, matching engines, e.t.c.\n\nIt is designed to combine the performance of pre-trained models with specialization for the custom task while avoiding slow and costly training.\n\n\n## Features\n\n* 🌀 **Warp-speed fast**: With the built-in caching mechanism, Quaterion enables you to train thousands of epochs with huge batch sizes even on *laptop GPU*.\n\n\u003Cp align=\"center\">\n  \u003Cimg alt=\"Regular vs Cached Fine-Tuning\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fqdrant_quaterion_readme_d3c74412426e.gif\">\n\u003C\u002Fp>\n\n* 🐈‍ **Small data compatible**: Pre-trained models with specially designed head layers allow you to benefit even from a dataset you can label *in one day*.\n\n\n* 🏗️ **Customizable**: Quaterion allows you to re-define any part of the framework, making it flexible even for large-scale and sophisticated training pipelines.\n\n\n* 🌌 **Scalable**: Quaterion is built on top of [PyTorch Lightning](https:\u002F\u002Fgithub.com\u002FLightning-AI\u002Flightning) and inherits all its scalability, cost-efficiency, and reliability perks.\n\n## Installation\n\nTL;DR:\n\nFor training:\n```bash\npip install quaterion\n```\n\nFor inference service:\n```bash\npip install quaterion-models\n```\n\n---\n\nQuaterion framework consists of two packages - `quaterion` and [`quaterion-models`](https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion-models).\n\nSince it is not always possible or convenient to represent a model in ONNX format (also, it **is supported**), the Quaterion keeps a very minimal collection of model classes, which might be required for model inference, in a [separate package](https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion-models).\n\nIt allows avoiding installing heavy training dependencies into inference infrastructure: `pip install quaterion-models`\n\nAt the same time, once you need to have a full arsenal of tools for training and debugging models, it is available in one package: `pip install quaterion`\n\n\n## Docs 📓\n\n* [Quick Start](https:\u002F\u002Fquaterion.qdrant.tech\u002Fgetting_started\u002Fquick_start.html) Guide\n* Minimal working [examples](.\u002Fexamples)\n\nFor a more in-depth dive, check out our end-to-end tutorials:\n\n- Fine-tuning NLP models - [Q&A systems](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fnlp_tutorial.html)\n- Fine-tuning CV models - [Similar Cars Search](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fcars-tutorial.html)\n\nTutorials for advanced features of the framework:\n\n- [Cache tutorial](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fcache_tutorial.html) - How to make training fast.\n- [Head Layers: Skip Connection](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fhead_layers_skip_connection.html) - How to avoid forgetting while fine-tuning\n- [Embedding Confidence](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fembedding_confidence.html) - how do I know that the model is sure about the output vector?\n- [Vector Collapse Prevention](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Ftriplet_loss_trick.html) - how to prevent vector space collapse in Triplet Loss\n\n\n## Community\n\n* Join our [Discord channel](https:\u002F\u002Fqdrant.to\u002Fdiscord)\n* Follow us on [Twitter](https:\u002F\u002Fqdrant.to\u002Ftwitter)\n* Subscribe to our [Newsletters](https:\u002F\u002Fqdrant.to\u002Fnewsletter)\n* Write us an email [info@qdrant.tech](mailto:info@qdrant.tech)\n\n## License\n\nQuaterion is licensed under the Apache License, Version 2.0. View a copy of the [License file](https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fblob\u002Fmaster\u002FLICENSE).\n","\u003Cp align=\"center\">\n  \u003Cimg height=\"100\" src=\"docs\u002Fimgs\u002Flogo.svg\" alt=\"Quaterion\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n    \u003Cb>用于微调相似度学习模型的极速框架\u003C\u002Fb>\n\u003C\u002Fp>\n\n\u003Cp align=center>\n    \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fquaterion\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fquaterion?label=pypi\" alt=\"版本\" \u002F>\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Factions\u002Fworkflows\u002Ftest.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg\" alt=\"测试状态\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fqdrant.to\u002Fdiscord\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Qdrant-5865F2.svg?logo=discord\" alt=\"Discord\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fquaterion.qdrant.tech\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLearn-Docs%20%26%20Tutorials-success\" alt=\"文档与教程\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n> 站在巨人的肩膀上的矮子，看得更远\n\nQuaterion 是一个用于微调相似度学习模型的框架。该框架解决了语义搜索、推荐系统、异常检测、极端分类、匹配引擎等任务中模型训练的“最后一公里”问题。\n\n它旨在将预训练模型的性能与针对特定任务的专业化相结合，同时避免缓慢而昂贵的训练过程。\n\n\n## 特性\n\n* 🌀 **极快的速度**：借助内置的缓存机制，Quaterion 即使在 *笔记本电脑 GPU* 上也能以超大批次进行数千轮的训练。\n\n\u003Cp align=\"center\">\n  \u003Cimg alt=\"常规微调 vs 缓存微调\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fqdrant_quaterion_readme_d3c74412426e.gif\">\n\u003C\u002Fp>\n\n* 🐈‍ **小数据友好**：通过特别设计的头部层，即使只有 *一天时间* 就能标注完的数据集，也能让预训练模型发挥出最大效用。\n\n\n* 🏗️ **可定制性**：Quaterion 允许用户重新定义框架的任何部分，使其能够灵活适应大规模且复杂的训练流程。\n\n\n* 🌌 **可扩展性**：Quaterion 构建在 [PyTorch Lightning](https:\u002F\u002Fgithub.com\u002FLightning-AI\u002Flightning) 之上，继承了其所有关于可扩展性、成本效益和可靠性的优势。\n\n\n## 安装\n\n简而言之：\n\n用于训练：\n```bash\npip install quaterion\n```\n\n用于推理服务：\n```bash\npip install quaterion-models\n```\n\n---\n\nQuaterion 框架由两个包组成——`quaterion` 和 [`quaterion-models`](https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion-models)。\n\n由于并非总是能够或方便地将模型表示为 ONNX 格式（尽管也 **支持**），Quaterion 将可能用于模型推理的极少量模型类放在一个 [独立的包](https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion-models) 中。\n\n这样可以避免在推理基础设施中安装繁重的训练依赖项：`pip install quaterion-models`。\n\n与此同时，当您需要完整的工具集来进行模型训练和调试时，只需安装一个包即可：`pip install quaterion`。\n\n\n## 文档 📓\n\n* [快速入门](https:\u002F\u002Fquaterion.qdrant.tech\u002Fgetting_started\u002Fquick_start.html) 指南\n* 最小可行的 [示例](.\u002Fexamples)\n\n若想深入了解，可查看我们的端到端教程：\n\n- 微调 NLP 模型——[问答系统](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fnlp_tutorial.html)\n- 微调 CV 模型——[相似汽车搜索](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fcars-tutorial.html)\n\n框架高级功能的教程：\n\n- [缓存教程](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fcache_tutorial.html)——如何让训练更快。\n- [头部层：跳跃连接](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fhead_layers_skip_connection.html)——如何在微调过程中避免遗忘。\n- [嵌入置信度](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Fembedding_confidence.html)——我如何知道模型对输出向量有把握？\n- [防止向量坍塌](https:\u002F\u002Fquaterion.qdrant.tech\u002Ftutorials\u002Ftriplet_loss_trick.html)——如何在三元组损失中避免向量空间坍塌。\n\n\n## 社区\n\n* 加入我们的 [Discord 频道](https:\u002F\u002Fqdrant.to\u002Fdiscord)\n* 关注我们的 [Twitter](https:\u002F\u002Fqdrant.to\u002Ftwitter)\n* 订阅我们的 [新闻通讯](https:\u002F\u002Fqdrant.to\u002Fnewsletter)\n* 发送邮件至 [info@qdrant.tech](mailto:info@qdrant.tech)\n\n## 许可证\n\nQuaterion 采用 Apache License, Version 2.0 许可证。请参阅 [许可证文件](https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fblob\u002Fmaster\u002FLICENSE)。","# Quaterion 快速上手指南\n\nQuaterion 是一个用于微调相似性学习模型（Similarity Learning）的高速框架。它专为语义搜索、推荐系统、异常检测等任务设计，旨在结合预训练模型的性能与特定任务的定制化能力，同时避免昂贵且缓慢的全量训练过程。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**：Linux, macOS 或 Windows\n*   **Python 版本**：3.8 及以上\n*   **硬件要求**：\n    *   **训练**：推荐使用 NVIDIA GPU（支持 CUDA），但得益于其内置缓存机制，即使在笔记本电脑 GPU 上也能进行高效的大批量训练。\n    *   **推理**：CPU 或 GPU 均可。\n*   **前置依赖**：\n    *   PyTorch\n    *   PyTorch Lightning（Quaterion 基于此构建，安装时会自动处理）\n\n## 安装步骤\n\nQuaterion 框架分为两个包：核心训练包 `quaterion` 和轻量级推理包 `quaterion-models`。\n\n### 1. 安装训练环境\n如果您需要进行模型微调、调试或完整开发，请安装主包：\n\n```bash\npip install quaterion\n```\n\n> **国内加速建议**：如果下载速度较慢，建议使用清华或阿里镜像源：\n> ```bash\n> pip install quaterion -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n> ```\n\n### 2. 安装推理环境（可选）\n如果您仅需在生产环境中部署模型进行推理（无需训练依赖），可安装轻量级包：\n\n```bash\npip install quaterion-models\n```\n\n## 基本使用\n\nQuaterion 的核心优势在于利用缓存机制加速训练，并允许通过自定义\"Head Layers\"轻松适配预训练模型。以下是一个最简化的微调流程示例。\n\n### 步骤 1: 导入必要的模块\n\n```python\nfrom quaterion import SimilarityModel\nfrom quaterion.dataset import DatasetColumn, GroupedDataset\nfrom quaterion.loss import ContrastiveLoss\nfrom quaterion.train import Trainer\nfrom torch.utils.data import DataLoader\n```\n\n### 步骤 2: 准备数据\nQuaterion 需要成对或分组的数据来进行相似性学习。假设我们有一个包含文本对的数据集：\n\n```python\n# 模拟数据：anchor (锚点), positive (正样本), negative (负样本)\ndata = [\n    {\"anchor\": \"如何重置密码\", \"positive\": \"忘记密码怎么办\", \"negative\": \"如何注册账号\"},\n    {\"anchor\": \"发货时间\", \"positive\": \"多久能收到货\", \"negative\": \"支持退货吗\"},\n    # ... 更多数据\n]\n\n# 创建数据集\ndataset = GroupedDataset(\n    data=data,\n    columns={\n        \"anchor\": DatasetColumn(\"anchor\"),\n        \"positive\": DatasetColumn(\"positive\"),\n        \"negative\": DatasetColumn(\"negative\")\n    }\n)\n\ndataloader = DataLoader(dataset, batch_size=32, shuffle=True)\n```\n\n### 步骤 3: 定义模型与损失函数\n加载预训练模型（如 BERT）并添加特定的头部层（Head Layer）以适应相似性任务。\n\n```python\n# 初始化模型，这里以 HuggingFace BERT 为例\nmodel = SimilarityModel(\n    encoder_name=\"bert-base-uncased\",\n    head_type=\"skip_connection\" # 使用跳过连接头，防止微调时遗忘预训练知识\n)\n\n# 定义损失函数，例如对比损失\nloss_fn = ContrastiveLoss(margin=0.5)\n```\n\n### 步骤 4: 启动训练\n利用 Quaterion 的 Trainer 进行训练。内置的缓存机制将自动优化嵌入计算速度。\n\n```python\ntrainer = Trainer(\n    model=model,\n    loss_function=loss_fn,\n    epochs=5,\n    device=\"cuda\" # 或 \"cpu\"\n)\n\n# 开始训练\ntrainer.fit(dataloader)\n```\n\n训练完成后，您可以直接使用微调后的模型生成嵌入向量，用于后续的语义搜索或匹配任务。\n\n---\n*更多高级教程（如缓存配置、向量防坍塌技巧等）请访问官方文档：https:\u002F\u002Fquaterion.qdrant.tech*","某电商初创团队急需构建一个“同款商品搜索”功能，希望用户上传图片即可找到风格相似的服饰，但面临标注数据少且算力有限的困境。\n\n### 没有 quaterion 时\n- **训练效率极低**：直接微调预训练模型需全量反向传播，在单张消费级显卡上跑完一个 epoch 耗时数小时，难以进行多轮迭代优化。\n- **小样本效果差**：仅有的几百张人工标注数据不足以支撑深层网络训练，模型极易过拟合，导致上线后搜索准确率低下。\n- **工程改造复杂**：为了适配特定的相似度计算任务，需要手动重写大量 PyTorch 训练循环和损失函数逻辑，开发周期被大幅拉长。\n- **资源成本高昂**：为了缩短训练时间，被迫租用昂贵的云端多卡集群，显著增加了初创项目的运营预算。\n\n### 使用 quaterion 后\n- **实现闪电般训练**：利用内置的缓存机制冻结主干网络，仅微调头部层，使得在笔记本 GPU 上也能以超大 Batch Size 快速完成数千个 epoch 的训练。\n- **小数据即时生效**：专为小样本设计的头部结构让团队仅需一天标注的数据即可训练出高精度模型，有效解决了冷启动难题。\n- **灵活定制流水线**：基于 PyTorch Lightning 的架构允许团队轻松替换损失函数或数据加载器，快速适配“以图搜图”的特殊业务逻辑。\n- **部署轻量低成本**：推理阶段仅需安装轻量的 `quaterion-models` 包，无需携带沉重的训练依赖，大幅降低了生产环境的服务器成本。\n\nquaterion 通过独特的缓存微调机制，让中小团队能在有限算力和数据下，低成本、高效率地落地高精度的语义搜索与推荐系统。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fqdrant_quaterion_52ed3839.png","qdrant","Qdrant","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fqdrant_ae834484.png","Creating advanced vector search technology",null,"info@qdrant.com","qdrant_engine","https:\u002F\u002Fqdrant.tech\u002F","https:\u002F\u002Fgithub.com\u002Fqdrant",[82],{"name":83,"color":84,"percentage":85},"Python","#3572A5",100,661,47,"2026-03-10T06:45:46","Apache-2.0","未说明","非必需，支持在笔记本电脑 GPU 上运行（依赖 PyTorch Lightning），具体型号、显存及 CUDA 版本未说明",{"notes":93,"python":90,"dependencies":94},"该框架分为训练包（quaterion）和推理包（quaterion-models），推理环境可仅安装轻量级的 quaterion-models 以避免安装沉重的训练依赖。内置缓存机制可大幅提升训练速度，支持小数据集微调。模型支持 ONNX 格式。",[95,64,96],"PyTorch Lightning","quaterion-models",[14],[99,100,101,102,103,104,105,106,107,108,109,110],"contrastive-learning","cosine-similarity","deep-learning","knn","machine-learning","metric-learning","nearest-neighbor-search","python","pytorch","pytorch-lightning","similarity-learning","similarity-search","2026-03-27T02:49:30.150509","2026-04-10T18:47:38.686746",[114,119,124,129,134,139],{"id":115,"question_zh":116,"answer_zh":117,"source_url":118},25391,"使用 XBM (Extended Batch Memory) 时遇到原地计算错误（Inplace computation error）怎么办？","该问题已在 v0.1.34 版本中修复，请升级 Quaterion：`pip install -U quaterion`。\n\n在修复发布前或如果仍遇到问题，建议在使用 XBM 时将距离度量改为余弦距离（Cosine distance），因为该错误主要出现在使用欧几里得距离（Euclidean distance）的上下文中。此外，新版本合并了更好的内存分配策略（semi-hard implementation），升级通常能解决此类内存相关问题。","https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fissues\u002F181",{"id":120,"question_zh":121,"answer_zh":122,"source_url":123},25392,"如何处理数据加载器缓存中的“张量比较的布尔值不明确”（Boolean value of tensor comparison is ambiguous）错误？","此错误通常发生在尝试直接使用 `in` 操作符检查张量是否存在于列表中时（例如 `if sample.obj not in unique_objects`），因为张量元素逐个比较会返回多个布尔值，导致条件判断失败。\n\n解决方案包括：\n1. 不要直接比较原始张量对象。\n2. 为每个对象生成唯一的哈希值（hash），维护一个独立存储唯一哈希值的容器（如 `unique_hashes`）。\n3. 在添加对象前，先检查其哈希值是否已存在于容器中。\n4. 或者，将张量包装在字典或自定义类中，并重写比较逻辑，仅基于特定的特征字段进行比较，而不是整个张量对象。该问题已在相关 PR (#34) 中修复。","https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fissues\u002F28",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},25393,"训练结束后无法复用数据加载器，或者遇到缓存相关的副作用怎么办？","默认情况下，`Quaterion.fit()` 结束时会自动调用 `unwrap_cache()`，这会导致数据加载器无法在训练后继续使用。\n\n解决方案：\n1. 在调用 `fit` 方法时，设置参数 `keep_cache=True`（如果版本支持），以跳过自动解包步骤：`Quaterion.fit(..., keep_cache=True)`。\n2. 如果需要手动控制，可以重命名或调整缓存方法，使其接受单个数据加载器作为参数，从而允许用户灵活地缓存多个数据加载器。\n3. 注意检查编码器恢复时的双重包装问题，确保在从 checkpoint 恢复时，编码器没有被重复包裹缓存层。","https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fissues\u002F50",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},25394,"如何在训练循环中同步模型检查点保存和可服务模型（servable model）的保存？","框架决定不直接在内部强制同步这两个过程，以避免增加与相似度学习无关的复杂逻辑。\n\n推荐的变通方案是在 `TrainableModel.save_servable` 方法中手动加载最佳检查点的状态：\n```python\ndef save_servable(...):\n    # ...\n    # 从指定的检查点路径加载状态字典\n    self.load_state_dict(torch.load(checkpoint_path)[\"state_dict\"])\n    # 恢复状态后，将其保存为可服务模型格式\n    # ... (后续保存逻辑)\n```\n通过这种方式，用户可以确保保存的是由 `ModelCheckpoint` 监控到的最佳模型状态，而不是训练结束时的最终状态。","https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fissues\u002F29",{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},25395,"在 Windows 上使用多进程数据加载器（num_workers > 0）配合缓存功能时报错怎么办？","在 Windows 上，结合使用多进程 DataLoader 和缓存功能可能会导致多进程上下文（mp context）被错误地设置为 `fork`，而 Windows 不支持 `fork`（应使用 `spawn`）。\n\n解决方法：\n1. 显式设置 multiprocessing 的 start method 为 `spawn`。\n2. 或者在配置缓存时，避免在多进程环境下自动触发可能导致上下文切换的逻辑。\n3. 如果可能，在 Windows 上调试时暂时将 `num_workers` 设置为 0，以确认是否为多进程引起的问题。维护者建议在 Windows 环境下特别注意 DataLoader 的初始化顺序和缓存配置的交互。","https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fissues\u002F49",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},25396,"项目对代码风格和贡献有什么具体要求？","为了保持代码质量，项目有以下要求：\n1. **类型注解**：所有函数必须包含 Python 类型注解（type annotations）。\n2. **形状注释**：在神经网络模型相关的代码中，每个张量变换操作后都应添加形状注释（shape comment），说明张量维度的变化（例如：`# [batch, seq_len, hidden]`）。\n3. **文档字符串**：遵循统一的 doc-string 格式。\n4. **提交信息**：需要遵守规范的 commit message 格式。\n5. **CI\u002FCD**：项目集成了自动化测试和 linter 检查，贡献代码前请确保本地通过相关检查。详细指南可参考 `CONTRIBUTING.md` 文件。","https:\u002F\u002Fgithub.com\u002Fqdrant\u002Fquaterion\u002Fissues\u002F9",[145,150,155,160],{"id":146,"version":147,"summary_zh":148,"released_at":149},162696,"v0.1.35","## 新增内容\n新的损失函数和错误修复\n### 功能\n- 添加了 Circle Loss #197\n- 添加了 FastAP Loss #199\n\n## 错误修复\n- 修复了采样器中的一个错误 #194\n- 更新依赖以提高兼容性 #201","2023-03-30T07:04:34",{"id":151,"version":152,"summary_zh":153,"released_at":154},162697,"v0.1.34","## 新增内容\n- 修复了在 XBM 上下文中因欧几里得距离矩阵优化而引起的 bug。","2022-12-13T08:53:38",{"id":156,"version":157,"summary_zh":158,"released_at":159},162698,"v0.1.33","## 新增内容\n- 更新了半硬三元组损失的实现，以避免在使用较大 XBM 缓冲区大小时出现内存不足导致的崩溃。","2022-12-08T09:57:41",{"id":161,"version":162,"summary_zh":163,"released_at":164},162699,"v0.1.31","## 新增功能\n- 在三元组损失中添加半硬挖掘，并引入跨批次记忆支持（#175）。\n- 为硬三元组损失添加软间隔变体（#178）。\n- 支持在 `SwitchHead` 中使用多个 `EncoderHead`，这对于类似 CLIP 的双塔编码器尤为有用；同时允许将元数据从 `Encoder` 传递到 `EncoderHead`，这也适用于传递掩码，例如注意力掩码（#180）。","2022-10-06T20:42:11"]