如何用 InsForge 的 pgvector 实现语义搜索向量列、嵌入生成与 HNSW 索引【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge本文解决一个具体任务在 InsForge 项目里用内置的 Postgres 和 pgvector 扩展搭出一条完整的语义搜索链路——创建向量列、服务端生成嵌入并写入、按余弦距离查询并在数据量变大后加上 HNSW 索引。每个 InsForge 项目都自带 pgvector见 pgvector 文档不需要额外安装数据库扩展。前置条件按 CLI 设置文档 完成登录并关联项目后还需要一个 OpenRouter API keyInsForge 的 Model Gateway 会为项目签发 OpenRouter key在 dashboard 中复制存到环境变量OPENROUTER_API_KEY用法详见 Model Gateway 文档 和 TypeScript AI 参考。npx insforge/cli login npx insforge/cli linkTypeScript AI 文档 明确要求不要把OPENROUTER_API_KEY放进浏览器 bundleOpenRouter 调用必须放在后端路由、server action 或 function 等服务端边界之后。下面的嵌入生成代码都应放在服务端。TypeScript 侧安装两个依赖npm install openai insforge/sdklatest第一步用迁移创建向量列InsForge 的 schema 变更走 迁移文件migrations/目录下按时间戳排序的.sql文件由 CLI 在事务中逐个应用成功记录写入system.custom_migrations流程是 forward-only 的。文件内不允许出现BEGIN/COMMIT/ROLLBACK。新建迁移文件npx insforge/cli db migrations new create-documents-table在生成的.sql文件中写入建表和建向量列的 SQL。注意vector(1536)的维度必须与嵌入模型一致——pgvector 文档 以 OpenRouter 的text-embedding-3-small1536 维为例create extension if not exists vector; create table documents ( id bigserial primary key, content text, embedding vector(1536) );应用迁移并核对历史npx insforge/cli db migrations up --all npx insforge/cli db migrations listup --all应用所有待执行的迁移也可以用up version只应用单个文件、up --to version应用到指定版本为止。list用于确认本次迁移已被记录。第二步服务端生成嵌入并写入嵌入在服务端生成后随行写入documents表代码与 pgvector 文档 一致import OpenAI from openai; import { createClient } from insforge/sdk; const openai new OpenAI({ baseURL: https://openrouter.ai/api/v1, apiKey: process.env.OPENROUTER_API_KEY, }); const insforge createClient({ projectId: process.env.INSFORGE_PROJECT_ID }); const { data } await openai.embeddings.create({ model: openai/text-embedding-3-small, input: hello world, }); await insforge.database.from(documents).insert({ content: hello world, embedding: data[0].embedding, });其中input是你要索引的文本data[0].embedding是 1536 维向量直接作为embedding列的值。SDK 客户端初始化除上文的projectId写法外SDK 安装说明 还给出了baseUrlanonKey的配置方式anon key 可用npx insforge/cli secrets get ANON_KEY或在 dashboard 的Install→API Keys中找到按你的部署方式取其一即可。TypeScript 数据库参考 中.insert()返回{ data, error }链上.select()可把刚插入的行取回来核对。第三步按余弦距离查询并包成 RPCpgvector 提供三种距离算子余弦距离、L2 距离-、内积#。最直接的查询是select id, content from documents order by embedding $1 limit 5;这里的$1是查询向量参数即把用户 query 用同一个模型openai/text-embedding-3-small嵌入后得到的 1536 维向量由客户端以参数形式传入。文档推荐把搜索包进 Postgres 函数、通过rpc()调用让距离计算留在服务端。先加一个函数同样写成迁移文件应用create or replace function match_documents( query_embedding vector(1536), match_count int default 5, match_threshold float default 0 ) returns table (id bigint, content text, similarity float) language sql stable as $$ select id, content, 1 - (embedding query_embedding) as similarity from documents where 1 - (embedding query_embedding) match_threshold order by embedding query_embedding limit match_count; $$;函数把余弦距离换算成similarity 1 - 距离match_threshold过滤低于阈值的匹配match_count控制返回条数默认 5。应用后TypeScript 侧按 数据库参考 的rpc()形式调用const { data, error } await insforge.database.rpc(match_documents, { query_embedding: embedding, // 与写入时同一模型生成的 1536 维向量 match_count: 5, match_threshold: 0.5, });embedding由你的 query 文本经第二步同样的openai.embeddings.create生成match_count和match_threshold按业务需要取值函数签名中有默认值5 和 0。第四步数据量超过 ~10k 行时加 HNSW 索引pgvector 文档 给出的判断标准是超过约 10k 行后再加 HNSW 索引同样通过迁移文件应用create index on documents using hnsw (embedding vector_cosine_ops);vector_cosine_ops与查询使用的余弦距离对应。文档总览中也说明 pgvector 同时支持 HNSW 和 IVFFlat 两类索引见 Database 总览。验证与限制迁移是否生效npx insforge/cli db migrations list中能看到本次迁移已应用的迁移不能原地修改只能新写一个 forward 迁移。查询是否工作match_documents的返回列为id、content、similarity其中similarity由函数计算1 - 余弦距离error为null且data非空说明链路通了。维度必须一致vector(1536)与text-embedding-3-small的 1536 维对应换嵌入模型时要同步改列维度。写入路径是 forward-only 的事务迁移迁移文件内不允许BEGIN/COMMIT/ROLLBACK。key 只在服务端OPENROUTER_API_KEY不能进浏览器 bundle嵌入生成必须放在服务端边界之后。更多算子和索引细节可参考文档末尾给出的 pgvector 与 OpenRouter embeddings 链接见 pgvector 文档InsForge 侧的 OpenRouter 配置见 Model Gateway 总览。【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考