Isaacus 集成 - 以编程方式使用文档

本指南将引导您了解如何开始使用 Isaacus 的 LangChain 集成来生成法律嵌入。

1. 设置您的账户

前往 Isaacus 平台创建一个新账户。

请务必妥善保管您的 API 密钥。创建后您将无法再次查看它。但不用担心，您可以随时生成一个新的。

2. 安装 isaacus API 客户端

现在您的账户已设置好，请安装 Isaacus LangChain 集成包。

pip install langchain-isaacus

uv add langchain-isaacus

3. 嵌入文档

我们的 API 客户端已安装，现在让我们嵌入第一个法律查询和文档。

首先，您需要 **使用您的 API 密钥初始化客户端**。您可以通过设置 ISAACUS_API_KEY 环境变量或直接传递密钥来实现，在本例中我们采用直接传递的方式。

我们将使用 Kanon 2 Embedder，截至 2025 年 10 月 20 日，它是 Massive Legal Embedding Benchmark 上全球最准确的法律嵌入模型。

from langchain_isaacus import IsaacusEmbeddings

# Create an Isaacus API client for Kanon 2 Embedder.
client = IsaacusEmbeddings(
    model="kanon-2-embedder",
    api_key="PASTE_YOUR_API_KEY_HERE",
    # dimensions=1792, # You may optionally wish to specify a lower dimension.
)

接下来，让我们获取一个要嵌入的法律文档。在本例中，我们将使用 GitHub 的服务条款.

tos = isaacus.Isaacus().get(path="https://examples.isaacus.com/github-tos.md", cast_to=str)

我们希望根据关于 GitHub 服务条款的搜索查询来检索它。

为此，我们将首先使用 API 客户端的 .embed_documents() 方法嵌入文档。使用此方法表示我们正在嵌入文档（而不是搜索查询），这对于确保我们的嵌入针对检索进行了优化非常重要（而不是其他任务如分类或句子相似度）。

document_embedding = client.embed_documents(texts=[tos])[0]

现在，让我们嵌入两个搜索查询，一个与文档明显相关，另一个明显不相关。这次我们将使用 API 客户端的 .embed_query() 方法，这表示我们正在嵌入搜索查询。

relevant_query_embedding = client.embed_query(text="What are GitHub's billing policies?")
irrelevant_query_embedding = client.embed_query(text="What are Microsoft's billing policies?")

为了评估查询与文档的相关性，我们可以计算它们的嵌入与文档嵌入之间的余弦相似度。

余弦相似度衡量两组数字的相似程度（具体来说是内积空间中两个向量之间夹角的余弦）。理论上，它的范围是 $$-1$$ 到 $$1$$，其中 $$1$$ 表示向量完全相同，$$0$$ 表示它们正交（即完全不相似），而 $$-1$$ 表示它们完全相反。然而，在实践中，对于文本嵌入来说，它往往在 $$0$$ 到 $$1$$ 之间（因为通常为非负值）。

Isaacus的嵌入器已经过优化，使得它们生成的嵌入的余弦相似度大致对应于原始文本在语义上的相似程度。然而，与Isaacus的通用分类器不同，Isaacus嵌入器的分数尚未被校准为可解释为概率，而仅作为相对相似度度量，这使得它们最适合用于对搜索结果进行排名。

为了方便起见，我们的Python示例使用了 numpy's dot 函数来计算我们嵌入的点积（由于我们所有的嵌入都是L2归一化的，因此这相当于它们的余弦相似度）。如果您愿意，可以使用另一个库来计算嵌入的余弦相似度（例如， torch 通过 torch.nn.functional.cosine_similarity），或者您可以编写自己的实现。

relevant_similarity = np.dot(relevant_query_embedding, document_embedding)
irrelevant_similarity = np.dot(irrelevant_query_embedding, document_embedding)

print(f"Similarity of relevant query to the document: {relevant_similarity * 100:.2f}")
print(f"Similarity of irrelevant query to the document: {irrelevant_similarity * 100:.2f}")

输出应该看起来像这样：

Similarity of relevant query to the document: 52.87
Similarity of irrelevant query to the document: 24.86

正如您所看到的，相关查询与文档的相似度得分远高于不相关查询，这表明我们的嵌入器已成功捕获了文本的语义含义。

就这样！您刚刚使用LangChain成功地将一份法律文档和查询通过Isaacus API进行了嵌入。