---

为人类和智能体构建高性能的AI 搜索应用。

快速入门

%pip install superlinked

from superlinked import framework as sl  
  
# 定义电影评论的模式  
class Review(sl.Schema):  
    id: sl.IdField  
    text: sl.String  
  
review = Review()  
space = sl.TextSimilaritySpace(text=review.text, model="all-MiniLM-L6-v2")  
index = sl.Index(space)  
query = sl.Query(index).find(review).similar(space, sl.Param("search")).select_all()  
  
# 设置并运行  
source = sl.InMemorySource(review)  
app = sl.InMemoryExecutor(sources=[source], indices=[index]).run()  
  
# 添加数据并搜索  
source.put([  
    {"id": "1", "text": "精彩的表演和出色的故事"},  
    {"id": "2", "text": "乏味的情节和糟糕的演技"}  
])  
  
result = app.query(query, search="卓越的表演")  
print(sl.PandasConverter.to_pandas(result))

目录

• 目录
• 快速入门
• 概述
• 动手教程
• 用例
• 在笔记本中实验
  • 安装 Superlinked 库
  • 运行示例：
• 生产环境部署
  • 支持的向量数据库
• 日志记录
• 资源
• 支持

概述

• 为什么：通过将元数据与您的非结构化数据一起编码为向量，提升向量搜索的相关性。
• 是什么：一个框架和可自托管的 REST API 服务器，用于连接您的数据、向量数据库和后端服务。
• 如何：您可以基于 sentence-transformers、open-clip 中的预训练编码器，以及针对数字、时间戳和分类数据的自定义编码器，构建自定义的数据和查询嵌入模型。请参阅下方的教程和用例笔记本以获取示例。

如果您喜欢我们的工作，请给我们点个赞！⭐

动手教程

等级	你将构建和学习的内容	立即尝试
从这里开始	嵌入文本 · 图像 · 数字 · 分类 · 时间 · 事件。	文本嵌入  图像嵌入  数值（最小-最大）  数值（相似度）  分类  最近性嵌入  事件效应
构建与扩展	组合空间或添加自定义/可选模式。	组合嵌入  自定义空间  可选字段
优化相关性	实时更新与查询时个性化。	动态参数  查询时权重  查询结果
搜索与筛选	自然语言搜索 + 硬性筛选。	自然语言查询  硬性筛选  查询选项  向量部分
分析与导出	离线抽取嵌入样本。	向量采样器
迈向多模态	统一的文本+图像空间。	多模态搜索

💡 还想了解更多？ 浏览我们文档中完整的功能与概念列表 →
https://docs.superlinked.com/concepts/overview

在笔记本中实验

让我们构建一个能够理解产品描述和评分的电商产品搜索：

运行笔记本示例：

首次运行需要一分钟下载嵌入模型。

%pip install superlinked

import json
import os

from superlinked import framework as sl


class Product(sl.Schema):
    id: sl.IdField
    description: sl.String
    rating: sl.Integer


product = Product()

description_space = sl.TextSimilaritySpace(
    text=product.description, model="Alibaba-NLP/gte-large-en-v1.5"
)
rating_space = sl.NumberSpace(
    number=product.rating, min_value=1, max_value=5, mode=sl.Mode.MAXIMUM
)
index = sl.Index([description_space, rating_space], fields=[product.rating])


# 定义你的查询和参数，以便在查询时直接设置，
# 或者让 LLM 使用 `natural_language_query` 参数为你填写。
# 别忘了设置你的 OpenAI API 密钥以解锁此功能。
query = (
    sl.Query(
        index,
        weights={
            description_space: sl.Param("description_weight"),
            rating_space: sl.Param("rating_weight"),
        },
    )
    .find(product)
    .similar(
        description_space,
        sl.Param(
            "description_query",
            description="用户查询中与产品描述相关的文本。",
        ),
    )
    .limit(sl.Param("limit"))
    .with_natural_query(
        sl.Param("natural_language_query"),
        sl.OpenAIClientConfig(api_key=os.environ["OPEN_AI_API_KEY"], model="gpt-4o")
    )
)

# 在内存中运行应用（也可使用服务器和 Apache Spark 执行器！）。
source = sl.InMemorySource(product)
executor = sl.InMemoryExecutor(sources=[source], indices=[index])
app = executor.run()

# 将数据摄入系统——索引更新及其他处理会自动进行。
source.put([
    {
        "id": 1,
        "description": "黑色预算型牙刷。正是您所需要的。",
        "rating": 1,
    },
    {
        "id": 2,
        "description": "毫不妥协打造的高端牙刷。",
        "rating": 5,
    },
    {
        "id": 3,
        "description": "专为聪明的21世纪男士设计的牙刷。",
        "rating": 3,
    },
])

result = app.query(query, natural_query="最好的牙刷", limit=1)

# 检查从查询中提取的参数
print(json.dumps(result.metadata, indent=2))

# 结果是那款五星级评价的产品。
sl.PandasConverter.to_pandas(result)

使用场景

通过我们的笔记本深入探讨每个使用场景如何受益于 Superlinked 框架。

• RAG：HR 知识库
• 语义搜索：电影、商业新闻、产品图片与描述
• 推荐系统：电子商务
• 分析：用户获取、关键词扩展

您可以在此处查看完整的示例列表：GitHub。

在生产环境中运行

只需一条命令，您就可以在本地或云端以 REST API 服务器的形式运行 Superlinked，使用 Superlinked Server。免费获得数据摄入和查询 API、嵌入模型推理以及深度向量数据库集成！

通过单一的声明式 Python 代码库，统一您的评估、摄入和推理堆栈。Superlinked 让您一次性定义数据模式、向量索引以及连接它们的计算 DAG，然后根据任务选择合适的执行器——内存中或服务器端。

如果您有兴趣了解如何大规模运行，请预约演示，以提前访问我们的托管云服务。

支持的向量数据库

Superlinked 将您的向量存储在您的向量数据库中，并与以下数据库深度集成：

• Redis
• MongoDB
• Qdrant
• TopK
• 我们接下来应该支持哪一种？

对向量数据库的优缺点感到好奇吗？我们的社区已经对比了44种向量数据库的30多项功能。

日志记录

Superlinked 框架的日志包含上下文信息，例如进程 ID 和包作用域。个人身份信息 (PII) 默认会被过滤掉，但可以通过将 SUPERLINKED_EXPOSE_PII 环境变量设置为 true 来显示。

资源

• 向量数据库对比：由 Superlinked 维护的开源协作式向量数据库比较。
• VectorHub：VectorHub 是一个免费且开源的学习平台，面向希望在其机器学习堆栈中加入向量检索功能的人士。

支持

需要帮助吗？我们随时为您提供支持：

• 如发现错误，请创建问题。
• 如需新功能，请在此处提交请求这里。
• 如有想法或疑问，可发起讨论。

请为每个主题创建单独的问题或讨论，以便我们更好地处理您的反馈。感谢您的贡献！

Superlinked 快速上手指南

⚠️ 重要提示：原 superlinked 仓库已弃用。团队已全面转向专注于解决生产环境推理瓶颈的新项目：Superlinked Inference Engine (SIE)。

• 新项目地址：https://github.com/superlinked/sie
• 本指南基于原框架的核心逻辑，适用于理解其多模态向量搜索构建理念及快速原型开发。

Superlinked 是一个用于构建高性能 AI 搜索应用的框架。它允许开发者将元数据（如数字、时间、类别）与非结构化数据（文本、图像）一起编码为丰富的多模态嵌入向量，从而超越简单的语义搜索，实现更精准的推荐、RAG 和分析应用。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python 版本：Python 3.8 或更高版本
• 前置依赖：
  • pip (Python 包管理工具)
  • 网络连接（首次运行需下载预训练的 Embedding 模型，如 sentence-transformers）

安装步骤

使用 pip 直接安装 Superlinked 库。国内开发者若遇到下载速度慢的问题，建议使用国内镜像源加速。

标准安装：

pip install superlinked

使用国内镜像源加速安装（推荐）：

pip install superlinked -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是一个最简单的示例，演示如何定义电影评论的数据结构，构建文本相似度空间，并在内存中执行搜索。

代码示例

%pip install superlinked

from superlinked import framework as sl  
  
# 1. 定义数据模式 (Schema)
class Review(sl.Schema):  
    id: sl.IdField  
    text: sl.String  
  
review = Review()  

# 2. 定义相似度空间 (Space) 和索引 (Index)
# 使用预训练模型 all-MiniLM-L6-v2 处理文本
space = sl.TextSimilaritySpace(text=review.text, model="all-MiniLM-L6-v2")  
index = sl.Index(space)  

# 3. 构建查询对象
# 查找与搜索参数相似的记录
query = sl.Query(index).find(review).similar(space, sl.Param("search")).select_all()  
  
# 4. 设置并运行执行器 (Executor)
source = sl.InMemorySource(review)  
app = sl.InMemoryExecutor(sources=[source], indices=[index]).run()  
  
# 5. 添加测试数据
source.put([  
    {"id": "1", "text": "Amazing acting and great story"},  
    {"id": "2", "text": "Boring plot with bad acting"}  
])  
  
# 6. 执行搜索并输出结果
result = app.query(query, search="excellent performance")  
print(sl.PandasConverter.to_pandas(result))

核心概念简述

• Schema: 定义数据的结构（类似数据库表结构）。
• Space: 定义特定字段的嵌入方式（如文本相似度、数值范围、时间远近等）。
• Index: 将多个 Space 组合在一起建立索引。
• Executor: 负责加载数据、运行模型并处理查询的执行引擎。

您可以直接在 Jupyter Notebook 或 Python 脚本中运行上述代码，首次运行时会自动下载所需的嵌入模型。