LlamaIndex OCIGenAIEmbeddings 深度解析OCI Generative AI 嵌入集成的 API 与实现细节【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文以 LlamaIndex 仓库中 OCI Generative AI 嵌入集成的 API 参考页docs/api_reference/api_reference/embeddings/oci_genai.md为核心完整梳理OCIGenAIEmbeddings类的安装方式、全部构造参数及其默认值、四种 OCI 鉴权模式在源码中的具体实现、支持模型清单与嵌入请求的底层调用链。读完本文后你可以直接复制可用的接入代码并理解每次get_text_embedding调用从 LlamaIndex 侧到 OCI SDK 的完整路径。API 参考页的生成方式该 API 参考页本身是一个极简的 mkdocs autodoc 存根见 oci_genai.md全部内容只有三行::: llama_index.embeddings.oci_genai options: members: - OCIGenAIEmbeddings它通过:::语法指向 Python 模块llama_index.embeddings.oci_genai并声明该页面只渲染OCIGenAIEmbeddings这一个成员。也就是说渲染后的 API 文档内容类 docstring、参数说明、示例代码全部来自集成包中的源码 docstring。这也是 LlamaIndex monorepo 中docs/api_reference下数百个集成页面的统一组织方式文档即源码 docstring 的投影。因此理解这一页 API等价于精读以下两个源文件核心实现base.py包导出init.py其中__all__ [OCIGenAIEmbeddings]与 autodoc 配置的 members 列表一一对应。安装与依赖集成包的 README.md 给出两步安装pip install llama-index-embeddings-oci-genai pip install -U oci第二行安装的是 Oracle 官方的 OCI Python SDK。从 pyproject.toml 可以确认精确的依赖约束与适用前提项目约束包版本0.5.0Python3.10,4.0OCI SDKoci2.125.3LlamaIndex 核心llama-index-core0.13.0,0.15注意源码中对oci包的导入采用了函数内懒加载策略__init__与_embed内部分别import oci未安装 OCI SDK 时不会在 import 阶段报错而是抛出带明确提示的ModuleNotFoundErrorraise ModuleNotFoundError( Could not import oci python package. Please make sure you have the oci package installed. )最小可用示例README 与类 docstring 中给出的是同一套接入范式创建嵌入器必须提供三个关键参数模型标识、服务 endpoint 与 compartment OCIDfrom llama_index.embeddings.oci_genai import OCIGenAIEmbeddings embedding OCIGenAIEmbeddings( model_nameMY_MODEL, service_endpointhttps://inference.generativeai.us-chicago-1.oci.oraclecloud.com, compartment_idMY_OCID, )其中service_endpoint的形式为https://inference.generativeai.region.oci.oraclecloud.comcompartment_id是目标 OCI compartment 的 OCID。创建之后即可使用 LlamaIndexBaseEmbedding提供的标准方法例如embedding.get_text_embedding(...)、embedding.get_query_embedding(...)和embedding.get_text_embedding_batch([...])。构造参数全解OCIGenAIEmbeddings.__init__的完整签名及默认值来源base.py 的 Pydantic Field 定义与__init__如下参数默认值说明model_name必填要使用的嵌入模型的 ID 或名称如cohere.embed-english-light-v3.0也可以传入专用端点 OCID见下文truncateEND对超出模型输入长度的文本的截断策略取值START/END/NONEinput_typeNone输入类型提示。不提供时查询侧自动使用SEARCH_QUERY、文档侧自动使用SEARCH_DOCUMENT模型相关可取search_query、search_document、classification、clustering等service_endpointNone服务 endpoint URLcompartment_idNonecompartment 的 OCIDauth_typeAPI_KEY鉴权类型可取API_KEY、SECURITY_TOKEN、INSTANCE_PRINCIPAL、RESOURCE_PRINCIPALauth_profileDEFAULT~/.oci/config中的 profile 名称auth_file_location~/.oci/configOCI 配置文件路径clientNone可选的现成 OCI 客户端对象提供后跳过内部客户端创建逻辑测试与高级注入场景用embed_batch_sizeDEFAULT_EMBED_BATCH_SIZE即 10批量嵌入的批大小来自核心包常量 constants.pycallback_managerNone回调管理器用于接入 LlamaIndex 的回调/遥测体系两个值得注意的实现细节input_type的“或”语义在_embed中构造请求时写的是input_typeself.input_type or input_type即构造时显式传入的input_type会覆盖按调用场景查询/文档自动推导的默认值。embed_batch_size的边界约束gt0, le2048定义在核心包基类 BaseEmbedding 中OCIGenAIEmbeddings通过继承获得无需自行声明。此外基类还向该集成提供了embeddings_cache嵌入缓存、rate_limiter限流器等字段to_payload()输出的观测载荷只包含class_name、model_name、embed_batch_size天然不含任何凭证信息。四种鉴权模式在源码中的实现OCIAuthType枚举定义了四种鉴权类型API_KEY、SECURITY_TOKEN、INSTANCE_PRINCIPAL、RESOURCE_PRINCIPAL。__init__中按auth_type分派构建oci.generative_ai_inference.GenerativeAiInferenceClient的client_kwargs每种模式的行为如下API_KEY默认调用oci.config.from_file(file_locationauth_file_location, profile_nameauth_profile)读取配置文件中的密钥信息并移除 signer走配置签名路径。这要求你本地已有包含相应 key/fingerprint 的~/.oci/configprofile。SECURITY_TOKEN先读取配置文件然后从配置中的key_file加载私钥再从security_token_file读取 token 字符串构造oci.auth.signers.SecurityTokenSigner(st_string, pk)作为 signer。INSTANCE_PRINCIPAL不依赖本地任何配置直接使用oci.auth.signers.InstancePrincipalsSecurityTokenSigner()适合在 OCI 计算实例上运行时通过实例身份访问。RESOURCE_PRINCIPAL使用oci.auth.signers.get_resource_principals_signer()适合在 OCI 函数等资源上下文中运行。传入以上之外的值时抛出ValueError提示 auth_type 非法。所有模式共享的客户端参数还包括retry_strategy: oci.retry.DEFAULT_RETRY_STRATEGY, timeout: (10, 240), # OCI Gen AI 服务的默认超时配置连接 10s / 读取 240s另外若鉴权构建过程中出现非导入类异常源码会统一包装为ValueError提示检查auth_profile、auth_file_location与auth_type是否有效。实际接入时的配套条件是你的 IAM profile/role 已具备访问 OCI Generative AI 服务的策略且如果使用了非默认的 config profile需要通过auth_profile与auth_file_location显式指明。支持模型清单源码中定义了SUPPORTED_MODELS集合并通过类方法list_supported_models()暴露SUPPORTED_MODELS { cohere.embed-v4.0, cohere.embed-english-v3.0, cohere.embed-english-light-v3.0, cohere.embed-multilingual-v3.0, cohere.embed-multilingual-light-v3.0, cohere.embed-english-light-v2.0, }从源码结构看model_name字段本身是一个自由字符串构造时并未强制校验其必须属于SUPPORTED_MODELS——该清单的用途是“该集成当前已知可对接”的 OCI Generative AI 托管嵌入模型查询时调用list_supported_models()即可枚举。嵌入请求的底层调用链以embedding.get_text_embedding(...)为例调用链为BaseEmbedding的批量/缓存逻辑 →_get_text_embedding(text)→_embed([text], input_typeSEARCH_DOCUMENT)→self._client.embed_text(request)。_embed的核心逻辑if self.model_name.startswith(CUSTOM_ENDPOINT_PREFIX): serving_mode models.DedicatedServingMode(endpoint_idself.model_name) else: serving_mode models.OnDemandServingMode(model_idself.model_name) request models.EmbedTextDetails( serving_modeserving_mode, compartment_idself.compartment_id, input_typeself.input_type or input_type, truncateself.truncate, inputstexts, ) response self._client.embed_text(request) return response.data.embeddings这里包含两个关键点按需服务 vs 专用端点自动切换当model_name以常量CUSTOM_ENDPOINT_PREFIX ocid1.generativeaiendpoint开头时说明你传入的是一个自托管的 OCI 专用推理端点 OCID此时构造DedicatedServingMode(endpoint_id...)否则按OnDemandServingMode(model_id...)调用 OCI 托管模型。同一个类因此同时覆盖了“托管模型”和“专属部署”两种接入形态。输入/查询双通道_get_query_embedding使用SEARCH_QUERY_get_text_embedding/_get_text_embeddings批量使用SEARCH_DOCUMENT。对 Cohere 系嵌入模型query 与 document 使用不同的输入前缀可获得更好的检索效果这个区分正是通过input_type参数下发给服务端的。从源码结构还可以确认一个值得知晓的细节异步方法_aget_text_embedding与_aget_query_embedding当前直接转调同步实现并未做真正的并发封装批量吞吐主要依靠embed_batch_size分批与get_text_embedding_batch的服务端批处理一次embed_text请求携带inputs列表。单元测试的验证方式集成包的测试展示了两种验证思路可作接入自检参考test_oci_genai.py通过client注入一个MagicMock客户端monkeypatchembed_text返回伪向量含 Hello 的文本返回[1.0, 0.0, 0.0]、含 World 的返回[0.0, 1.0, 0.0]再断言get_text_embedding_batch([Hello, World])的输出与期望一致。这也正是client参数存在的意义——它让整条嵌入路径可以在完全不触达真实 OCI 服务的情况下被验证。该测试同时参数化覆盖了cohere.embed-english-light-v3.0与cohere.embed-english-v3.0两个模型 ID。test_embeddings_oci_genai.py检查OCIGenAIEmbeddings的 MRO 中包含BaseEmbedding保证接口契约get_text_embedding等公共方法可用不被破坏。小结与适用前提OCIGenAIEmbeddings是 LlamaIndex 对接 OCI Generative AI 嵌入能力llama-index-embeddings-oci-genai当前版本 0.5.0的唯一入口类其能力边界由源码清晰划定四种 OCI 鉴权模式、按需/专用端点双服务模式、query/document 输入类型区分、批量嵌入与缓存/限流能力继承自核心基类。适用前提包括Python 3.10、安装oci2.125.3与llama-index-core0.13.0,0.15、具备访问 OCI Generative AI 服务的 IAM 策略与有效的~/.oci/config或改用实例/资源主体鉴权。在 RAG 管道中将该嵌入器作为VectorStoreIndex/检索器的 embedding 组件传入即可用法与其他 LlamaIndex 嵌入集成完全一致。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LlamaIndex OCIGenAIEmbeddings 深度解析：OCI Generative AI 嵌入集成的 API 与实现细节
LlamaIndex OCIGenAIEmbeddings 深度解析OCI Generative AI 嵌入集成的 API 与实现细节【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文以 LlamaIndex 仓库中 OCI Generative AI 嵌入集成的 API 参考页docs/api_reference/api_reference/embeddings/oci_genai.md为核心完整梳理OCIGenAIEmbeddings类的安装方式、全部构造参数及其默认值、四种 OCI 鉴权模式在源码中的具体实现、支持模型清单与嵌入请求的底层调用链。读完本文后你可以直接复制可用的接入代码并理解每次get_text_embedding调用从 LlamaIndex 侧到 OCI SDK 的完整路径。API 参考页的生成方式该 API 参考页本身是一个极简的 mkdocs autodoc 存根见 oci_genai.md全部内容只有三行::: llama_index.embeddings.oci_genai options: members: - OCIGenAIEmbeddings它通过:::语法指向 Python 模块llama_index.embeddings.oci_genai并声明该页面只渲染OCIGenAIEmbeddings这一个成员。也就是说渲染后的 API 文档内容类 docstring、参数说明、示例代码全部来自集成包中的源码 docstring。这也是 LlamaIndex monorepo 中docs/api_reference下数百个集成页面的统一组织方式文档即源码 docstring 的投影。因此理解这一页 API等价于精读以下两个源文件核心实现base.py包导出init.py其中__all__ [OCIGenAIEmbeddings]与 autodoc 配置的 members 列表一一对应。安装与依赖集成包的 README.md 给出两步安装pip install llama-index-embeddings-oci-genai pip install -U oci第二行安装的是 Oracle 官方的 OCI Python SDK。从 pyproject.toml 可以确认精确的依赖约束与适用前提项目约束包版本0.5.0Python3.10,4.0OCI SDKoci2.125.3LlamaIndex 核心llama-index-core0.13.0,0.15注意源码中对oci包的导入采用了函数内懒加载策略__init__与_embed内部分别import oci未安装 OCI SDK 时不会在 import 阶段报错而是抛出带明确提示的ModuleNotFoundErrorraise ModuleNotFoundError( Could not import oci python package. Please make sure you have the oci package installed. )最小可用示例README 与类 docstring 中给出的是同一套接入范式创建嵌入器必须提供三个关键参数模型标识、服务 endpoint 与 compartment OCIDfrom llama_index.embeddings.oci_genai import OCIGenAIEmbeddings embedding OCIGenAIEmbeddings( model_nameMY_MODEL, service_endpointhttps://inference.generativeai.us-chicago-1.oci.oraclecloud.com, compartment_idMY_OCID, )其中service_endpoint的形式为https://inference.generativeai.region.oci.oraclecloud.comcompartment_id是目标 OCI compartment 的 OCID。创建之后即可使用 LlamaIndexBaseEmbedding提供的标准方法例如embedding.get_text_embedding(...)、embedding.get_query_embedding(...)和embedding.get_text_embedding_batch([...])。构造参数全解OCIGenAIEmbeddings.__init__的完整签名及默认值来源base.py 的 Pydantic Field 定义与__init__如下参数默认值说明model_name必填要使用的嵌入模型的 ID 或名称如cohere.embed-english-light-v3.0也可以传入专用端点 OCID见下文truncateEND对超出模型输入长度的文本的截断策略取值START/END/NONEinput_typeNone输入类型提示。不提供时查询侧自动使用SEARCH_QUERY、文档侧自动使用SEARCH_DOCUMENT模型相关可取search_query、search_document、classification、clustering等service_endpointNone服务 endpoint URLcompartment_idNonecompartment 的 OCIDauth_typeAPI_KEY鉴权类型可取API_KEY、SECURITY_TOKEN、INSTANCE_PRINCIPAL、RESOURCE_PRINCIPALauth_profileDEFAULT~/.oci/config中的 profile 名称auth_file_location~/.oci/configOCI 配置文件路径clientNone可选的现成 OCI 客户端对象提供后跳过内部客户端创建逻辑测试与高级注入场景用embed_batch_sizeDEFAULT_EMBED_BATCH_SIZE即 10批量嵌入的批大小来自核心包常量 constants.pycallback_managerNone回调管理器用于接入 LlamaIndex 的回调/遥测体系两个值得注意的实现细节input_type的“或”语义在_embed中构造请求时写的是input_typeself.input_type or input_type即构造时显式传入的input_type会覆盖按调用场景查询/文档自动推导的默认值。embed_batch_size的边界约束gt0, le2048定义在核心包基类 BaseEmbedding 中OCIGenAIEmbeddings通过继承获得无需自行声明。此外基类还向该集成提供了embeddings_cache嵌入缓存、rate_limiter限流器等字段to_payload()输出的观测载荷只包含class_name、model_name、embed_batch_size天然不含任何凭证信息。四种鉴权模式在源码中的实现OCIAuthType枚举定义了四种鉴权类型API_KEY、SECURITY_TOKEN、INSTANCE_PRINCIPAL、RESOURCE_PRINCIPAL。__init__中按auth_type分派构建oci.generative_ai_inference.GenerativeAiInferenceClient的client_kwargs每种模式的行为如下API_KEY默认调用oci.config.from_file(file_locationauth_file_location, profile_nameauth_profile)读取配置文件中的密钥信息并移除 signer走配置签名路径。这要求你本地已有包含相应 key/fingerprint 的~/.oci/configprofile。SECURITY_TOKEN先读取配置文件然后从配置中的key_file加载私钥再从security_token_file读取 token 字符串构造oci.auth.signers.SecurityTokenSigner(st_string, pk)作为 signer。INSTANCE_PRINCIPAL不依赖本地任何配置直接使用oci.auth.signers.InstancePrincipalsSecurityTokenSigner()适合在 OCI 计算实例上运行时通过实例身份访问。RESOURCE_PRINCIPAL使用oci.auth.signers.get_resource_principals_signer()适合在 OCI 函数等资源上下文中运行。传入以上之外的值时抛出ValueError提示 auth_type 非法。所有模式共享的客户端参数还包括retry_strategy: oci.retry.DEFAULT_RETRY_STRATEGY, timeout: (10, 240), # OCI Gen AI 服务的默认超时配置连接 10s / 读取 240s另外若鉴权构建过程中出现非导入类异常源码会统一包装为ValueError提示检查auth_profile、auth_file_location与auth_type是否有效。实际接入时的配套条件是你的 IAM profile/role 已具备访问 OCI Generative AI 服务的策略且如果使用了非默认的 config profile需要通过auth_profile与auth_file_location显式指明。支持模型清单源码中定义了SUPPORTED_MODELS集合并通过类方法list_supported_models()暴露SUPPORTED_MODELS { cohere.embed-v4.0, cohere.embed-english-v3.0, cohere.embed-english-light-v3.0, cohere.embed-multilingual-v3.0, cohere.embed-multilingual-light-v3.0, cohere.embed-english-light-v2.0, }从源码结构看model_name字段本身是一个自由字符串构造时并未强制校验其必须属于SUPPORTED_MODELS——该清单的用途是“该集成当前已知可对接”的 OCI Generative AI 托管嵌入模型查询时调用list_supported_models()即可枚举。嵌入请求的底层调用链以embedding.get_text_embedding(...)为例调用链为BaseEmbedding的批量/缓存逻辑 →_get_text_embedding(text)→_embed([text], input_typeSEARCH_DOCUMENT)→self._client.embed_text(request)。_embed的核心逻辑if self.model_name.startswith(CUSTOM_ENDPOINT_PREFIX): serving_mode models.DedicatedServingMode(endpoint_idself.model_name) else: serving_mode models.OnDemandServingMode(model_idself.model_name) request models.EmbedTextDetails( serving_modeserving_mode, compartment_idself.compartment_id, input_typeself.input_type or input_type, truncateself.truncate, inputstexts, ) response self._client.embed_text(request) return response.data.embeddings这里包含两个关键点按需服务 vs 专用端点自动切换当model_name以常量CUSTOM_ENDPOINT_PREFIX ocid1.generativeaiendpoint开头时说明你传入的是一个自托管的 OCI 专用推理端点 OCID此时构造DedicatedServingMode(endpoint_id...)否则按OnDemandServingMode(model_id...)调用 OCI 托管模型。同一个类因此同时覆盖了“托管模型”和“专属部署”两种接入形态。输入/查询双通道_get_query_embedding使用SEARCH_QUERY_get_text_embedding/_get_text_embeddings批量使用SEARCH_DOCUMENT。对 Cohere 系嵌入模型query 与 document 使用不同的输入前缀可获得更好的检索效果这个区分正是通过input_type参数下发给服务端的。从源码结构还可以确认一个值得知晓的细节异步方法_aget_text_embedding与_aget_query_embedding当前直接转调同步实现并未做真正的并发封装批量吞吐主要依靠embed_batch_size分批与get_text_embedding_batch的服务端批处理一次embed_text请求携带inputs列表。单元测试的验证方式集成包的测试展示了两种验证思路可作接入自检参考test_oci_genai.py通过client注入一个MagicMock客户端monkeypatchembed_text返回伪向量含 Hello 的文本返回[1.0, 0.0, 0.0]、含 World 的返回[0.0, 1.0, 0.0]再断言get_text_embedding_batch([Hello, World])的输出与期望一致。这也正是client参数存在的意义——它让整条嵌入路径可以在完全不触达真实 OCI 服务的情况下被验证。该测试同时参数化覆盖了cohere.embed-english-light-v3.0与cohere.embed-english-v3.0两个模型 ID。test_embeddings_oci_genai.py检查OCIGenAIEmbeddings的 MRO 中包含BaseEmbedding保证接口契约get_text_embedding等公共方法可用不被破坏。小结与适用前提OCIGenAIEmbeddings是 LlamaIndex 对接 OCI Generative AI 嵌入能力llama-index-embeddings-oci-genai当前版本 0.5.0的唯一入口类其能力边界由源码清晰划定四种 OCI 鉴权模式、按需/专用端点双服务模式、query/document 输入类型区分、批量嵌入与缓存/限流能力继承自核心基类。适用前提包括Python 3.10、安装oci2.125.3与llama-index-core0.13.0,0.15、具备访问 OCI Generative AI 服务的 IAM 策略与有效的~/.oci/config或改用实例/资源主体鉴权。在 RAG 管道中将该嵌入器作为VectorStoreIndex/检索器的 embedding 组件传入即可用法与其他 LlamaIndex 嵌入集成完全一致。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![Kubernetes 一致性测试套件文档机制全解析：从 `[Conformance]` 注释到自动化清单的生成链路](http://pic.xiahunao.cn/yaotu/Kubernetes 一致性测试套件文档机制全解析：从 `[Conformance]` 注释到自动化清单的生成链路)
