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

使用 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-core0.13.0,0.15与isaacus0.9.0要求 Python3.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 平台账号前往 Isaacus Platform 注册页创建账号登录后在计费Billing页面添加支付方式以领取免费额度在 API Keys 页面创建新的 API Key。创建 API Key 时请立即妥善保存——它只在创建时显示一次之后无法再次查看但可以随时重新生成。2. 导出环境变量推荐通过环境变量注入凭据export ISAACUS_API_KEYyour-api-key-here可选地也可以自定义 API 基础地址export ISAACUS_BASE_URLhttps://api.isaacus.com/v13. 凭据解析规则源码级从 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/v1base.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(fEmbedding dimension: {len(embedding)})批量文本嵌入texts [Contract clause 1, Contract clause 2, Legal precedent] embeddings embedding_model.get_text_embedding_batch(texts) print(fNumber 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( modelkanon-2-embedder, # 当前唯一可用的模型 api_keyos.getenv(ISAACUS_API_KEY), dimensions1792, # 可选显式指定维度 taskretrieval/document, # 针对文档检索优化 timeout60.0, ) print(embedding_model.get_text_embedding(Legal text to embed))完整的参数表如下默认值以当前仓库源码为准参数类型默认值说明modelstrkanon-2-embedder使用的嵌入模型api_keystros.getenv(ISAACUS_API_KEY)Isaacus API Keybase_urlstrhttps://api.isaacus.com/v1Isaacus API 基础地址dimensionsintNone使用模型默认维度可选降低嵌入维度taskstrNone任务类型retrieval/query或retrieval/documentoverflow_strategystrdrop_end溢出处理策略drop_end或Nonetimeoutfloat60.0请求超时时间秒embed_batch_sizeint100嵌入调用批次大小参数如何进入请求源码级在 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.AsyncIsaacusbase.py 第 140-149 行二者共享同一组api_key、base_url与timeout。查询嵌入与文档嵌入法律检索场景中查询与文档的嵌入目标不同。Isaacus 支持任务专用优化使用taskretrieval/query编码搜索查询使用taskretrieval/document编码文档。这样做的意义在于让查询向量与文档向量落在更一致的语义空间中提升检索相关性。from llama_index.embeddings.isaacus import IsaacusEmbedding # 文档侧显式指定文档检索任务 doc_embedder IsaacusEmbedding(taskretrieval/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时也会自动携带taskretrieval/query。这是因为 base.py 中的_get_query_embedding在内部调用了_get_text_embedding(query, task_overrideretrieval/query)而get_text_embedding则保持实例级task配置默认为空。测试 test_get_query_embedding_uses_retrieval_query_task 专门验证了请求中确实携带了taskretrieval/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(textThis is a contract clause about payment terms.), Document(textThis is a contract clause about termination.), ] # 构建向量索引 index VectorStoreIndex.from_documents(documents) # 查询索引 query_engine index.as_query_engine( llmllm, response_modecompact, similarity_top_k5 ) response query_engine.query(What are the payment terms?) print(response)相似度计算与检索排序在嵌入阶段之外IsaacusEmbedding返回的是标准浮点向量列表可直接与 LlamaIndex 的similarity工具配合在examples中可以看到计算查询与候选文档相似度的完整流程。对于法律合同条款检索、判例检索等场景建议同时配合taskretrieval/document与get_query_embedding使用以获得任务对齐的向量空间。可用模型当前集成支持以下嵌入模型kanon-2-embedderIsaacus 面向法律领域的嵌入模型其默认输出维度为 1792见测试 test_embedding_dimensions并支持通过dimensions参数降维。说明README 中提及该模型在 Massive Legal Embedding BenchmarkMLEB上的评测表现与 Isaacus 官方文档中的更多模型信息属于供应商对外发布的内容使用前建议以 Isaacus 官方文档与当前DEFAULT_ISAACUS_MODEL常量为准。错误处理集成对常见故障场景做了显式处理相关行为均可在 base.py 与 测试文件 中验证场景行为缺少 API Key初始化时抛出ValueError参数与环境变量均未提供API 未返回嵌入抛出ValueError(No embeddings returned from API)网络错误 / API 错误记录错误日志后抛出ValueError(Unable to embed text: ...)无效的 API 配置依赖isaacus客户端在校验 base_url、timeout 等配置时给出相应错误其中同步与异步路径的错误处理逻辑完全一致。实测中建议在应用层捕获ValueError并配合日志模块 logger定位具体原因。测试与示例运行运行测试套件仓库为集成包提供了完整的单元测试基于 pytest mock不依赖真实 APIuv run -- pytest带覆盖率运行uv run -- pytest --covllama_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.pybasic_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考