pgai 扩展接入 Voyage AISQL 中生成 Embedding 与 Rerank 的完整配置与实战指南【免费下载链接】pgaiA suite of tools to develop RAG, semantic search, and other AI applications more easily with PostgreSQL项目地址: https://gitcode.com/GitHub_Trending/pg/pgai本文基于 pgai 仓库中的 Voyage AI 使用文档完整讲解如何在 PostgreSQL 中配置 Voyage AI API Key、通过 SQL 调用ai.voyageai_embed生成文本向量并结合仓库源码与测试用例深入剖析函数签名、密钥解析链路、input_type参数语义以及批量嵌入、重排序Rerank等进阶用法帮助读者把 Voyage AI 能力直接落地到数据库内的 RAG 与语义检索场景中。一、模块概览Voyage AI 在 pgai 中提供哪些函数pgai 是一个构建在 PostgreSQL 上的 AI 工具套件通过aischema 下的一组 plpython3u 函数把第三方模型能力引入数据库。Voyage AI 集成对应的 SQL 定义位于 017-voyageai.sql共提供 4 个函数函数输入返回用途ai.voyageai_embed(model, input_text, ...)单条文本vector生成单条文本的嵌入向量ai.voyageai_embed(model, input_texts, ...)文本数组text[]表(index int, embedding vector)批量生成嵌入按下标配对ai.voyageai_rerank(model, query, documents, ...)查询 文档数组jsonb对候选文档重排序返回原始 JSON 结构ai.voyageai_rerank_simple(model, query, documents, ...)查询 文档数组表(index int, document text, relevance_score float8)重排序结果的行式视图便于直接 SQL 查询从 017-voyageai.sql#L5-L27 的函数定义可以看到所有函数都具备以下共同特征language plpython3u在数据库进程内以 Python 执行直接调用官方voyageaiPython SDKsecurity invoker以调用者身份执行权限受控immutable parallel safe同一输入产生同一结果可参与并行计划set search_path to pg_catalog, pg_temp锁定搜索路径避免被用户 schema 中的同名对象劫持。函数体的核心逻辑统一为三步解析 API Keyai.secrets.get_secret→ 可选地用verbose追踪请求ai.utils.VerboseRequestTrace→ 委托给 ai/voyageai.py 中的 Python 封装执行 SDK 调用。二、配置 Voyage AI API Key调用 Voyage AI 函数需要一个 Voyage AI API Key。pgai 提供了多种配置途径官方文档对生产环境的建议是通过环境变量设置对测试与开发则建议用会话级参数session level parameter完整的各方案对比与安全性建议见 Handling API keys 文档。2.1 开发测试会话级参数PGOPTIONS这是原文档给出的最快上手方式分三步在 shell 中把 Key 设为环境变量export VOYAGE_API_KEYthis-is-my-super-secret-api-key-dont-tell连接数据库时通过会话级参数注入PGOPTIONS-c ai.voyage_api_key$VOYAGE_API_KEY psql -d postgres://username:passwordhost:port/database-name直接运行 AI 查询无需在每次函数调用中重复指定 KeySELECT * FROM ai.voyageai_embed(voyage-3-lite, sample text to embed);ai.voyage_api_key这个 GUC 只在整个 psql 会话期间有效。之所以这样可行从源码 secrets.py#L91-L96 可以看到密钥解析的第一步就是读取 GUCsecret_name_lower secret_name.lower() secret get_guc_value(plpy, fai.{secret_name_lower}, ) if secret ! : return secret由于 Voyage AI 的默认密钥名是VOYAGE_API_KEY见 ai/voyageai.py#L5 的DEFAULT_KEY_NAME VOYAGE_API_KEY对应读取的 GUC 正好是ai.voyage_api_key。测试用例 test_voyageai.py#L43-L60 中也用set_config(ai.voyage_api_key, ...)验证了这条通路。2.2 生产环境PostgreSQL 进程的环境变量自托管场景下推荐把VOYAGE_API_KEY设为PostgreSQL 进程本身可见的环境变量Systemd 的Environment、docker run -e或 Docker Compose 的environment段。这与 2.1 的区别在于环境变量对所有会话全局生效且 Key 不出现在任何 SQL 语句或连接参数里。具体配置方式Systemd / Docker / Docker Compose 三种示例在 Handling API keys 文档中有完整说明。2.3 逐次调用api_key/api_key_name参数每个 voyageai 函数都额外接受api_key text default null与api_key_name text default null两个参数。密钥解析的完整优先级从 secrets.py#L24-L46 的get_secret实现可以确认显式传入的api_key参数最高优先级直接返回api_key_name指定的密钥名未指定时回退到默认值VOYAGE_API_KEY按密钥名依次查找GUCai.name→ 同名大写的环境变量 → 外部密钥管理服务Timescale Cloud 场景下由ai.external_functions_executor_url开启。需要注意的安全性细节Handling API keys 文档指出把api_key以文本字面量传入会使值出现在 PostgreSQL 日志中可能泄露密钥推荐用绑定变量方式传入例如通过 psql 变量 \bindpsql -d postgres://username:passwordhost:port/database-name -v my_api_key$VOYAGE_API_KEYSELECT * FROM ai.voyageai_embed(voyage-3-lite, sample text, api_key $1) \bind :my_api_key \g当所有途径都解析不到密钥时函数会抛出missing VOYAGE_API_KEY secret错误——测试用例 test_voyageai.py#L25-L40 正是断言了这一报错可作为配置失败时的排查基准。三、用 SQL 生成 Embedding3.1 单条文本嵌入指定模型请求一条文本的嵌入向量SELECT ai.voyageai_embed ( voyage-3-lite , the purple elephant sits on a red mushroom );返回结果为 pgvector 类型SQL 签名中返回extschema:vector.vector即vectorschema 下的vector类型形如voyageai_embed -------------------------------------------------------- [0.005978798,-0.020522336,...-0.0022857306,-0.023699166] (1 row)从 017-voyageai.sql#L18-L24 可以看到实现细节单文本版本实际上是把input_text包成单元素列表[input_text]后复用 Python 层的ai.voyageai.embed再取返回元组中的向量部分。因此单文本版本与数组版本共用同一套底层调用逻辑。3.2 批量嵌入传入文本数组对数组输入函数以表函数形式返回每行带一个与输入顺序对应的indexSELECT ai.voyageai_embed ( voyage-3-lite , array[Timescale is Postgres made Powerful, the purple elephant sits on a red mushroom] );SQL 签名见 017-voyageai.sql#L34-L63返回table(index int, embedding vector)。Python 层通过yield from enumerate(response.embeddings)ai/voyageai.py#L28按枚举顺序产出保证下标与输入一一对应——这一点在测试 test_voyageai.py#L131-L143 中用count(*) 2得到验证。批量接口是向量化文档表时的关键能力可以一次 SDK 请求处理多个 chunk减少往返开销。3.3 指定input_typedocument 与 queryVoyage AI API 允许把input_type设为document或query或不设。对检索库文本用document、对检索式用query可以增强检索质量SELECT ai.voyageai_embed ( voyage-3-lite , A query , input_type query );实现上input_type非空时才会被放进请求参数017-voyageai.sql#L21-L23透传给voyageai.Client.embed(input, model..., input_type...)ai/voyageai.py#L25。测试 test_voyageai.py#L81-L110 验证了同一文本分别以input_type document和input_type query嵌入会得到不同的向量证明该参数确实生效。实践建议索引阶段写向量入库统一用document查询阶段用户检索式统一用query并保持全链路一致。3.4 其他函数参数除model与输入外两个voyageai_embed重载还接受api_key/api_key_name见第二节的密钥配置verbose boolean default false为true时通过VerboseRequestTrace017-voyageai.sql#L19把底层 HTTP 请求过程追踪出来便于排查 API 调用问题。模型与维度的对应关系可以从测试用例中确认均断言vector_dimsvoyage-3-lite为 512 维test_voyageai.py#L63-L78voyage-3.5-lite、voyage-3.5、voyage-3-large默认均为 1024 维test_voyageai.py#L146-L203。创建存储嵌入的表时vector列的维度需要与所选模型输出一致。3.5 进阶维度降维与量化输出从 Python 层源码 ai/voyageai.py#L8-L28 可以看到embed封装还接受truncation、output_dimension、output_dtype三个参数非空时透传给 SDK。测试套件 test_voyageai.py 中包含大量对这些参数组合的验证用例覆盖了 Voyage AI 的矩阵降维Matryoshka 式与量化能力output_dimension可把输出降到 256 / 512 / 2048 等维度如 L206-L263与批量输入可组合使用output_dtype支持float默认、int8、uint8、binary、ubinary量化。其中binary/ubinary会按 8 位打包维度数相应变为output_dimension/8测试断言 1024/8128、512/864见 L344-L385。量化向量在入库时会被转回浮点存储因此vector_dims反映的是打包后的存储维度。量化与降维对大语料场景的价值在于直接压缩向量列的存储与距离计算开销。另外对超长输入的稳健性也有测试佐证repeat(hello world, 20000)约 21.6 万字符仍能正常返回 512 维向量test_voyageai.py#L113-L128。四、Rerank在 SQL 中做二次重排序除嵌入外017-voyageai.sql 还提供了重排序函数适合“向量召回 top-N 后再精排”的 RAG 管道。4.1ai.voyageai_rerank返回 jsonb函数签名L68-L98为rerank(model, query, documents text[], api_key, api_key_name, top_k integer, truncation boolean, verbose)返回jsonb。Python 层把 SDK 响应序列化为包含results每项含index、document、relevance_score与total_tokens的结构ai/voyageai.py#L50-L63。典型用法取自测试 test_voyageai.py#L409-L437with x as ( select ai.voyageai_rerank ( rerank-2.5 , How long does it take for two programmers to work on something? , array [ $$Good programmers dont just write programs. They build a working vocabulary.$$ , One of the best programming skills you can have is knowing when to walk away for awhile. , What one programmer can do in one month, two programmers can do in two months. , how much wood would a woodchuck chuck if a woodchuck could chuck wood? ] , api_key绑定变量 ) as actual ) select y.index as actual from x cross join lateral jsonb_to_recordset(x.actual-results) y(index int, relevance_score float8) order by y.relevance_score desc limit 1;top_k参数可限制返回条数测试 L440-L466 验证top_k2时jsonb_array_length(results) 2truncation控制超长文档是否截断。4.2ai.voyageai_rerank_simple行式结果如果不想手动解析 jsonbvoyageai_rerank_simpleL103-L139是纯 SQL 实现的便捷封装它内部调用voyageai_rerank后用jsonb_to_recordset展开results再unnest(documents) with ordinality按index关联回原文直接返回(index, document, relevance_score float8)三列表可像普通表函数一样order by relevance_score desc limit n。五、实现细节与验证方式底层调用链。以单文本嵌入为例完整链路为ai.voyageai_embedplpython3u→ai.secrets.get_secretGUC/环境变量/密钥管理服务三级解析→ai.voyageai.embed组装 SDK 参数、VerboseRequestTrace可选追踪→voyageai.Client.embed官方 SDK→ 元组枚举产出向量。整条链路在数据库进程内完成向量直接落到 pgvector 类型无需应用层中转。测试与运行前提。功能测试位于 test_voyageai.py文件头通过os.getenv(VOYAGE_API_KEY)控制开关未设置该环境变量或设为0时整模块pytest.skip设置后测试连接postgres://test127.0.0.1:5432/test实例执行真实 API 调用。这意味着跑该测试套件需要本地 PostgreSQL含 pgvector和一个可用的 Voyage AI Key测试同时覆盖了“无密钥报错、GUC 注入、api_key参数、input_type、多模型维度、降维量化、批量输入、rerank 与 top_k”等场景可作为本文各用法正确性的对照依据。权限与安全。所有函数均为security invoker且parallel safe密钥解析还受ai.secret_permissions表约束secrets.py#L49-L72 会校验调用者是否有权读取指定密钥多租户库中可以按角色精细控制谁能使用哪个 API Key。六、小结围绕 voyageai.md 文档的主线可以归纳为配 Key开发期用PGOPTIONS-c ai.voyage_api_key...会话参数最快生产期建议 PostgreSQL 进程环境变量或云厂商密钥管理敏感场景避免把 Key 写进 SQL 日志做嵌入ai.voyageai_embed同时支持单文本与数组批量两种形态input_type区分 document/query 提升检索质量做精排ai.voyageai_rerank/ai.voyageai_rerank_simple让“召回 重排”整条 RAG 链路都可以在 SQL 内闭环。关键参考文件文档 projects/extension/docs/model_calling/voyageai.md 与 projects/extension/docs/security/handling-api-keys.mdSQL 定义 projects/extension/sql/idempotent/017-voyageai.sqlPython 封装 projects/extension/ai/voyageai.py 与 projects/extension/ai/secrets.py测试 projects/extension/tests/test_voyageai.py。【免费下载链接】pgaiA suite of tools to develop RAG, semantic search, and other AI applications more easily with PostgreSQL项目地址: https://gitcode.com/GitHub_Trending/pg/pgai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考