企业官网建设流程全解析

使用 Isaacus 法律文本 Embedding 集成：LlamaIndex 中的 Kanon 2 Embedder 实战指南

【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index

导读

llama-index-embeddings-isaacus是 LlamaIndex 生态中面向法律领域文本的嵌入（Embedding）集成包，它封装了 Isaacus 平台的 Kanon 2 Embedder 模型，让开发者可以在 LlamaIndex 的索引、检索与问答链路中直接使用面向法律文本优化的向量表示。读完本文，你将掌握该集成的安装配置、同步与异步调用方式、任务专用（query/document）嵌入策略、与VectorStoreIndex的完整整合流程，以及其底层请求参数与错误处理机制。

集成概览

Isaacus 是专注于法律 AI 的模型提供商，其 Kanon 2 Embedder 是一个面向法律文本的嵌入模型。该集成包的核心是一个继承自 LlamaIndexBaseEmbedding的IsaacusEmbedding类，位于 llama_index/embeddings/isaacus/base.py，对外通过 llama_index/embeddings/isaacus/init.py 导出。由于它实现了 LlamaIndex 标准的嵌入接口，因此可以无缝嵌入到索引构建、检索器与查询引擎中，无需修改既有代码。

从 pyproject.toml 可以看到，该包依赖llama-index-core>=0.13.0,<0.15与isaacus>=0.9.0，要求 Python>=3.10,<4.0，当前版本为0.2.0，采用 MIT 许可证。

安装

推荐使用 pip 安装，先安装 LlamaIndex 主包，再安装该集成：

pip install llama-index pip install llama-index-embeddings-isaacus

若使用 uv 管理依赖，也可直接在项目根目录通过uv add llama-index-embeddings-isaacus引入（仓库的 uv.lock 已锁定开发环境依赖）。

环境准备与 API 配置

1. 注册 Isaacus 账号并获取 API Key

使用该集成前需要拥有 Isaacus 平台账号：

1. 前往 Isaacus Platform 注册页创建账号；
2. 登录后在计费（Billing）页面添加支付方式，以领取免费额度；
3. 在 API Keys 页面创建新的 API Key。

创建 API Key 时请立即妥善保存——它只在创建时显示一次，之后无法再次查看，但可以随时重新生成。

2. 导出环境变量

推荐通过环境变量注入凭据：

export ISAACUS_API_KEY="your-api-key-here"

可选地，也可以自定义 API 基础地址：

export ISAACUS_BASE_URL="https://api.isaacus.com/v1"

3. 凭据解析规则（源码级）

从 base.py 的初始化逻辑可以看出凭据解析的优先级：

• API Key：优先使用构造参数api_key，否则读取环境变量ISAACUS_API_KEY；两者皆无时抛出ValueError，提示"API key is required. Set ISAACUS_API_KEY environment variable or pass api_key parameter."；
• Base URL：优先使用构造参数base_url，其次环境变量ISAACUS_BASE_URL，最后回退到常量DEFAULT_ISAACUS_API_BASE = "https://api.isaacus.com/v1"（base.py 第 19 行）。

基本用法

单个文本嵌入

from llama_index.embeddings.isaacus import IsaacusEmbedding # 初始化 Isaacus 嵌入模型（默认读取 ISAACUS_API_KEY 环境变量） embedding_model = IsaacusEmbedding() # 获取单个文本的嵌入向量 embedding = embedding_model.get_text_embedding("Legal document text here") print(f"Embedding dimension: {len(embedding)}")

批量文本嵌入

texts = ["Contract clause 1", "Contract clause 2", "Legal precedent"] embeddings = embedding_model.get_text_embedding_batch(texts) print(f"Number of embeddings: {len(embeddings)}")

值得说明的是，Isaacus API 原生支持批量嵌入，因此get_text_embedding_batch会把整个文本列表一次性发给 API（见 base.py 中的_get_text_embeddings），并在返回后按每个向量对象的index字段排序，从而保证结果与输入顺序一致——这一点也被 tests/test_isaacus_embeddings.py 中的test_get_text_embeddings_maintains_order所验证。

配置参数详解

IsaacusEmbedding支持通过构造参数定制嵌入行为：

import os from llama_index.embeddings.isaacus import IsaacusEmbedding embedding_model = IsaacusEmbedding( model="kanon-2-embedder", # 当前唯一可用的模型 api_key=os.getenv("ISAACUS_API_KEY"), dimensions=1792, # 可选：显式指定维度 task="retrieval/document", # 针对文档检索优化 timeout=60.0, ) print(embedding_model.get_text_embedding("Legal text to embed"))

完整的参数表如下（默认值以当前仓库源码为准）：

参数如何进入请求（源码级）

在 base.py 的_prepare_request_params中，请求体由以下规则组装：

• model与texts始终携带；
• task：若调用方传入了task_override则优先使用，否则使用实例级task，两者皆空则不携带（测试test_prepare_request_params_task_override验证了覆盖优先级）；
• dimensions：仅当显式设置时加入请求，用于降低嵌入维度；
• overflow_strategy：默认"drop_end"，用于处理超长文本截断时的溢出策略。

初始化时会同时创建同步客户端isaacus.Isaacus与异步客户端isaacus.AsyncIsaacus（base.py 第 140-149 行），二者共享同一组api_key、base_url与timeout。

查询嵌入与文档嵌入

法律检索场景中，查询与文档的嵌入目标不同。Isaacus 支持任务专用优化：使用task="retrieval/query"编码搜索查询，使用task="retrieval/document"编码文档。这样做的意义在于让查询向量与文档向量落在更一致的语义空间中，提升检索相关性。

from llama_index.embeddings.isaacus import IsaacusEmbedding # 文档侧：显式指定文档检索任务 doc_embedder = IsaacusEmbedding(task="retrieval/document") doc_embedding = doc_embedder.get_text_embedding("This is a legal document.") # 查询侧：get_query_embedding 默认使用 retrieval/query 任务 query_embedder = IsaacusEmbedding() query_embedding = query_embedder.get_query_embedding( "Find documents about contracts" )

一个容易被忽略但重要的实现细节是：即使你没有在实例上设置task，调用get_query_embedding时也会自动携带task="retrieval/query"。这是因为 base.py 中的_get_query_embedding在内部调用了_get_text_embedding(query, task_override="retrieval/query")；而get_text_embedding则保持实例级task配置（默认为空）。测试 test_get_query_embedding_uses_retrieval_query_task 专门验证了请求中确实携带了task="retrieval/query"。

在 examples/basic_usage.py 中，官方示例进一步演示了用llama_index.core.base.embeddings.base提供的similarity函数计算查询与各文档之间的余弦相似度，用于排序检索结果。

异步用法

该集成完整支持异步 API，便于在高并发服务中避免阻塞事件循环：

import asyncio from llama_index.embeddings.isaacus import IsaacusEmbedding async def get_embeddings_async(): embedding_model = IsaacusEmbedding() # 异步获取单个嵌入 embedding = await embedding_model.aget_text_embedding("Legal text here") # 异步批量嵌入 embeddings = await embedding_model.aget_text_embedding_batch( ["Text 1", "Text 2"] ) return embedding, embeddings result = asyncio.run(get_embeddings_async()) print(result)

异步接口与同步接口一一对应：aget_text_embedding/aget_text_embedding_batch/aget_query_embedding，其内部逻辑与同步版本相同（通过_aclient调用AsyncIsaacus客户端，见 base.py 第 225-269 行），同样支持 query 任务的自动覆盖与批次结果按索引排序。可运行的完整示例见 examples/async_usage.py。

与 LlamaIndex 深度集成

作为全局嵌入模型接入

通过Settings.embed_model，可以把 Isaacus 嵌入模型设置为全局默认，之后所有索引构建与检索都会自动使用它：

from llama_index.core import VectorStoreIndex, Settings from llama_index.core import Document from llama_index.embeddings.isaacus import IsaacusEmbedding from llama_index.llms.openai import OpenAI # 设置 LLM llm = OpenAI() Settings.llm = llm # 全局设置 Isaacus 嵌入模型 Settings.embed_model = IsaacusEmbedding() # 创建文档 documents = [ Document(text="This is a contract clause about payment terms."), Document(text="This is a contract clause about termination."), ] # 构建向量索引 index = VectorStoreIndex.from_documents(documents) # 查询索引 query_engine = index.as_query_engine( llm=llm, response_mode="compact", similarity_top_k=5 ) response = query_engine.query("What are the payment terms?") print(response)

相似度计算与检索排序

在嵌入阶段之外，IsaacusEmbedding返回的是标准浮点向量列表，可直接与 LlamaIndex 的similarity工具配合，在examples中可以看到计算查询与候选文档相似度的完整流程。对于法律合同条款检索、判例检索等场景，建议同时配合task="retrieval/document"与get_query_embedding使用，以获得任务对齐的向量空间。

可用模型

当前集成支持以下嵌入模型：

• kanon-2-embedder：Isaacus 面向法律领域的嵌入模型，其默认输出维度为 1792（见测试 test_embedding_dimensions），并支持通过dimensions参数降维。

说明：README 中提及该模型在 Massive Legal Embedding Benchmark（MLEB）上的评测表现与 Isaacus 官方文档中的更多模型信息，属于供应商对外发布的内容，使用前建议以 Isaacus 官方文档与当前DEFAULT_ISAACUS_MODEL常量为准。

错误处理

集成对常见故障场景做了显式处理（相关行为均可在 base.py 与 测试文件 中验证）：

其中同步与异步路径的错误处理逻辑完全一致。实测中建议在应用层捕获ValueError并配合日志（模块 logger）定位具体原因。

测试与示例运行

运行测试套件

仓库为集成包提供了完整的单元测试（基于 pytest + mock，不依赖真实 API）：

uv run -- pytest

带覆盖率运行：

uv run -- pytest --cov=llama_index tests/

也可以使用包内 Makefile 的make test（等价于pytest tests）。测试覆盖了参数初始化、环境变量注入、缺失 Key 报错、query/document 任务传递、批量顺序保持、异步路径以及请求参数组装等关键行为。

运行可运行示例

examples目录提供了同步与异步两个可直接运行的示例：

cd llama-index-integrations/embeddings/llama-index-embeddings-isaacus/examples uv run python basic_usage.py

basic_usage.py会依次演示单条嵌入、批量嵌入、query/document 任务优化以及相似度排序；async_usage.py则是相同流程的异步版本。运行前请确保环境变量ISAACUS_API_KEY已正确设置。

小结

llama-index-embeddings-isaacus为法律领域文本检索提供了一条低接入成本的路径：IsaacusEmbedding完全遵循 LlamaIndex 的BaseEmbedding接口，支持同步/异步、单条/批量、query/document 任务优化与维度裁剪，并且可以通过Settings.embed_model一键接入既有索引与查询引擎。结合其请求参数组装、凭据解析与错误处理等源码实现细节，开发者可以在合同审查、判例检索、法规问答等场景中快速构建可用的法律语义检索能力。

【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index