用APEX低代码平台演示向量近似检索：从建表到交互页面

APEX这个词最近热度不低有人问的是安卓的APEX模块有人问的是某款游戏但在数据库和低代码开发圈子里APEX通常指的是Oracle的Application Express——一个只需要浏览器就能把数据库变成完整Web应用的低代码平台。今天这篇文章要聊的正好是把这两件事拉到一起用APEX搭一个可交互的小程序直观体验一下向量近似检索到底是什么效果。如果你只是听过“向量数据库”“近似最近邻搜索”这些概念却一直没机会亲手把玩这篇文章就是给你准备的。我会从环境准备讲到建表、生成向量、建立索引再到在APEX里做页面交互全程把关键SQL和配置贴出来。你可以照着一步步操作在很短时间里看到一个能输入文字、输出Top-N相似结果的可视化界面。整个过程不要求你有机器学习背景也不要求你精通低代码开发只要你熟悉基础SQL和APEX页面开发流程就够了。1. 从一个疑问开始向量近似检索到底在解决什么问题1.1 传统检索的瓶颈先从一个很常见的需求说起。假定你手里有一张内容表里面存了很多文档标题和正文片段用户输入“数据库查询变慢了怎么办”你希望系统把含义最接近的几篇文章推荐出来。用SQL怎么实现这个搜索最直接的想法是LIKE %查询%或者INSTR(title, 查询) 0。但这里有个绕不开的问题SQL的匹配是基于字符的它只能找到“字面上包含某个词”的记录。如果用户问的是“系统响应很慢怎么排查”而数据库里的文章标题是“MySQL执行计划分析”两边字面重合度很低但语义上明明高度相关LIKE根本无能为力。传统数据库里另一条路是做全文索引比如Oracle Text它能做分词、能处理同义词、能按相关性打分比LIKE强很多但本质上还是在“文本关键词”这个圈子里打转。它不知道“手机”和“智能手机”之间的语义差别也不知道“查一下价格”和“多少钱”是同一个意思。那怎么办把内容变成“向量”然后在一个不是字符空间、而是语义空间里去比较相似度。这就是向量检索的出发点。1.2 把数据变成向量向量听起来很高深实际可以这样理解通过一个神经网络模型把一段文本“压缩”成一个固定长度的数组比如384个浮点数。这个数组就是这段文本在语义空间里的坐标。模型训练得越好意思相近的两句话在这个空间里的坐标就越接近。我常用的一个类比是“特征指纹”。每个物品原本是一堆无法直接比较的原始信息向量化之后就能像比对指纹一样去比较了。比较的方式也很简单算两个向量之间的距离。距离小说明语义相近距离大说明八竿子打不着。这个思路不仅仅适合文本。图片、音频、用户行为序列都可以被编码成向量。这也是为什么向量检索这几年这么火——它把各种非结构化数据统一成了同一种可计算的形式。1.3 “近似”二字的真实含义标题里有个关键词是“近似”。为什么是近似而不是精确试想一下如果你的数据量很小只有100条记录精确计算最暴力的方法也很快——把查询向量和历史向量一个接一个算距离取最小的几个就行。这在数学上叫“暴力检索”或者“精确最近邻搜索”。但当数据量到了百万、千万甚至上亿每次查询都把所有向量遍历一遍代价就到了不可接受的程度。哪怕单条向量距离计算只要0.01毫秒一亿条也要1000秒这还没算IO开销。所以工业界想了很多办法用“索引结构”让查询不用遍历全部数据用一定程度的准确性换取数量级的速度提升。HNSW、IVF、PQ这些算法各有各的招但核心思想都是我给你一个接近最优的结果而不是保证最优。换句话说“近似检索”不是“结果不准”而是在大规模数据下的速度与精度的取舍。在绝大多数推荐、搜索、去重场景里Top-5里返回3条高质量结果远比等上十几秒返回10条精确结果更有实际价值。这个点在演示程序里可以通过对比“暴力精确检索”和“近似检索”的耗时与结果差异得到非常直观的感受。2. 为什么用APEX来搭建这个体验程序2.1 对比几种“演示向量检索”的方式想把这个检索能力做成一个能直观体验的东西有几种常见做法。第一种是用Python脚本直接跑。把向量化、检索、打印结果的逻辑写在一个脚本里运行完在终端看到几行输出。这样做足够简单也能验证算法但问题是从头到尾看不到“程序的样子”不直观。尤其当你想表达“向量检索如何使用”时一个黑乎乎的终端窗口说服力有限。第二种是自己搭一个完整Web应用比如FastAPI做后端、Vue或React做前端。这种方案的好处是完全可控界面可以做得非常漂亮。但代价也明显你需要处理路由、跨域、打包、部署还要写不少页面代码。让一个以SQL和数据库为主要工具的开发者为做一个演示去搭一套前端工程有点杀鸡用牛刀的感觉。第三种就是APEX。用它做这种演示程序我实测下来有几个其他方案给不了的优点页面组件几乎不用写前端代码交互式报表直接绑定SQL就能展示结果PL/SQL能搞定所有后端逻辑最关键的是——它和数据库天然在一台机器上数据表、向量索引、检索SQL、页面全在一个环境里闭环。不需要把数据导出成文件不需要调HTTP接口传数据所有环节都在SQL和PL/SQL的语境里完成。对于“我要把向量近似检索这件事演示清楚”这个目标来说这个体验是我试过最顺滑的。三种方案的对比大致是这样的方案开发成本可视化程度数据操作便利性适合场景Python脚本低很低一般需要自己连接数据库快速验证算法Web前端后端高高一般需要写接口正式产品原型APEX低代码低高高原生SQL直接操作内部工具、演示Demo、数据分析2.2 APEX 与数据库向量能力的组合优势如果你的数据库是Oracle 23ai这个组合的优势会更明显。23ai内置了VECTOR数据类型、向量索引、向量距离计算函数全套能力都在数据库内部。APEX新版对VECTOR类型也有比较好的支持你甚至可以在交互式报表的SQL里直接查询VECTOR列然后在前端展示距离和相似度。也就是说从建表、产生向量、建索引到Web页面写SQL查询、显示结果整个链路你不需要离开APEX和数据库这两个环境。相比传统方案要同时管理“数据库”和“中间件/前端服务”两条线这个组合把复杂度压缩到了最低。对于演示场景这种“低摩擦”非常重要。因为演示目的不是证明“你能写一个Web应用”而是让观众把注意力聚焦在向量检索本身的逻辑和效果上。环境越简单核心点越突出。2.3 没有 Oracle 23ai 怎么办备选方案有的朋友环境里还是19c或者旧版本没有VECTOR类型。也不要紧还有一条路可以走用外部向量数据库或向量化服务把检索封装成REST接口然后在APEX里通过REST数据源来调用。具体做法也不复杂。比如你在PostgreSQL里安装了pgvector或者单独部署了一套向量数据库然后写一个非常薄的HTTP接口接收文本、返回Top-N结果。APEX这边创建一个REST数据源页面上按钮触发流程把查询词通过接口发出去拿回结果后展现在交互式报表里。这种方案的优点是不依赖特定数据库版本缺点是链路变长调试起来要考虑网络、超时、数据格式。所以我个人的建议是如果只是为了体验和理解向量检索优先考虑有原生VECTOR类型的数据库加上APEX的组合如果你所在团队已经有一套向量数据库只是想接一个前端Demo那REST方案反而是更贴近生产环境的做法。3. 环境准备与数据建模3.1 版本与权限要求我这次演示使用的环境是Oracle Database 23ai基础版本APEX版本是4没有额外装其他组件。你需要确认以下几点数据库版本支持VECTOR类型和向量索引。Oracle 23c之后叫23aiVECTOR相关能力默认可用。APEX版本不要太旧建议使用24.x或更高。APEX 24.1开始对向量类型的显示和绑定支持更好。账号需要有建表、创建索引、执行PL/SQL的权限。如果要调用外部模型服务还需要配置网络访问权限ACL这点后面会提到。浏览器端只需要一个能访问APEX应用构建器的现代浏览器不需要安装客户端。实际操作中我见过不少环境是因为APEX版本太老导致页面里无法正常绑定VECTOR类型变量最后绕了一个大圈。所以如果可能尽量用新版本。3.2 选一个直观的演示场景为了把“向量近似检索”这件事演示得足够自然我选了一个“迷你知识库检索”的场景。具体来说我在一张表里放了几篇类似FAQ或技术文章的数据每篇文章有ID、标题、正文片段外加一个VECTOR列存放整段文本经过模型编码后的向量。这个场景的好处是结果非常好解释。用户在页面上输入一句话系统返回Top-5的文章标题和正文片段同时带上相似度分数。即便不太懂技术的人也能立刻理解“系统是根据语义相似度帮我找到了相关文档”。3.3 建表并插入测试数据建表SQL很简单核心就是那个VECTOR列。Oracle的VECTOR类型可以指定维度这里我们用一个384维的向量对应sentence-transformers里all-MiniLM-L6-v2模型的输出维度。建表语句如下create table doc_vectors ( id number generated always as identity primary key, title varchar2(200), content clob, content_vec vector(384) );然后插入几条测试数据。为了后面对比效果我在数据里故意放了一些标题相近但内容侧重不同的文档insert into doc_vectors (title, content) values (MySQL慢查询分析, 当数据库出现慢查询时首先要看执行计划确认是否走了索引...), (Redis缓存穿透解决方案, 缓存穿透是指请求绕过缓存直接打到数据库可以通过布隆过滤器...), (APEX低代码开发入门, Oracle APEX是基于数据库的Web应用开发平台适合快速构建内部系统...), (数据库连接池调优, 连接池大小不是越大越好要根据数据库并发能力和响应时间综合评估...), (微服务网关选型, 微服务架构下网关负责路由、鉴权、限流常见选型包括...); commit;注意这个阶段content_vec还是空的需要先向量化再回填。展示向量检索之前必须保证每行数据都有一条非空的向量否则会出现空结果。3.4 向量从哪来生成向量的两种路径生成向量的常见方式有两种我分别说一下你可以根据环境选。方式一用Python脚本调用sentence-transformers库生成向量然后通过SQL写回数据库。这种方式最灵活不依赖数据库的外部模型服务适合在没有大模型API的环境下操作。from sentence_transformers import SentenceTransformer import oracledb model SentenceTransformer(all-MiniLM-L6-v2) conn oracledb.connect(userdemo, password***, dsnlocalhost:1521/freepdb1) cursor conn.cursor() rows cursor.execute(select id, title, content from doc_vectors).fetchall() for rid, title, content in rows: text title (content or ) vec model.encode(text).tolist() cursor.execute( update doc_vectors set content_vec :v where id :id, v[ ,.join(f{x:.6f} for x in vec) ], idrid ) conn.commit()这段代码的思路是先把每行数据拼成一段文本然后编码成向量再把向量转换成Oracle VECTOR能接受的字符串格式写入。VECTOR类型的字面量就是用方括号包起来的浮点数列表比如[0.123, 0.456, -0.789]。这个点很多第一次接触的人会忽略。方式二如果数据库配置了外部模型服务也可以直接用内置函数生成向量。Oracle 23ai 的VECTOR_EMBEDDING函数可以通过REST调用大模型的Embedding接口。使用前提是配置好模型端点。示意的用法是update doc_vectors set content_vec vector_embedding(model_id, title || || content);这个方案的好处是不用单独跑Python脚本但需要处理网络ACL、模型端点配置等问题第一次搭可能会踩坑。如果你只是想快速看到效果建议先走Python脚本方式。4. 向量索引的建立与参数选择4.1 HNSW 与 IVF 该选谁数据有了之后下一步是建立向量索引。Oracle 23ai支持两类向量索引HNSW和IVF。HNSW全称是Hierarchical Navigable Small World思路是把向量组织成一张多层的图查询时从上层开始逐层往下导航可以快速找到相近的节点。它的特点是构建快、查询也快对中小数据集特别友好而且不需要单独的训练过程。IVF全称是Inverted File Index思路是先对向量做聚类把数据分到若干个桶里查询时只搜索几个最有可能包含相近向量的桶。它的问题是构建时需要先训练聚类模型而且对数据分布有一定要求但它在超大向量集上内存消耗更可控。在实际演示场景里数据量也就是几十条到几千条我建议直接用HNSW。它不是“凑合能用”而是这个量级下体验最好的选择。IVF更适合百万级以上的场景演示阶段没必要引入聚类训练的概念。4.2 建索引的 SQL 与参数说明创建HNSW向量索引的SQL并不复杂但有几个参数值得认真对待。create vector index doc_vectors_hnsw_idx on doc_vectors(content_vec) organization inmemory neighbor graph distance cosine with target accuracy 95;这个语句里distance cosine表示索引和查询都使用余弦距离with target accuracy 95表示我们希望近似检索的召回精度达到95%。Oracle会基于这个目标自动选择部分索引参数。如果你想手动控制更多细节HNSW还有neighbors和connections这类参数。neighbors决定了每个节点在图中保存多少个邻居值越大召回率越高但内存占用和构建时间也越大。connections决定了每层的连接数影响检索时的导航效率。我给中小数据集的建议是neighbors设为40到64之间connections设为16到32之间。初学者不需要过度调参先用默认值或一个中等数值跑通流程后再慢慢试。4.3 三种距离算法怎么选向量近似检索里最常见的三种距离计算方式是余弦距离、欧氏距离、内积距离它们的适用场景差别很大。距离算法计算公式特点适用场景余弦距离只管方向不管长度文本语义相似度最常用欧氏距离方向和长度都考虑图像特征、原始空间距离内积距离与向量长度强相关推荐系统打分场景在文本检索演示里我最推荐余弦距离。因为文本编码模型的输出向量通常会做归一化或者即使不归一化语义相似度也更偏向“方向一致”而不是“长度一致”。如果你在实测中发现结果不太对劲先检查一下索引和查询SQL用的是不是同一种距离算法这两处不匹配是新手最容易踩的坑。4.4 验证索引是否生效索引建好不等于检索时一定会用它。Oracle的优化器在某些情况下可能选择全表扫描然后精确计算尤其在数据量很小的时候。可以用EXPLAIN PLAN确认一下。explain plan for select id, title from doc_vectors order by vector_distance(content_vec, :query_vec, COSINE) fetch first 5 rows only; select * from table(dbms_xplan.display);如果执行计划里出现了VECTOR INDEX相关字样说明索引被用上了。如果看到的是全表扫描不要慌可以给SQL加一个提示select /* INDEX(doc_vectors doc_vectors_hnsw_idx) */ ...在演示环境里数据量小的时候全表扫描也不慢但不展示索引的执行计划会少了一个教学点。这个小细节在演示时加进去观众会觉得你考虑得很周全。5. 在 APEX 中实现可视化检索页面5.1 页面布局与组件规划APEX里创建一个空白页我建议按下面的结构来设计一个文本输入项比如P1_QUERY用来接收用户输入的查询内容。一个按钮比如RUN_SEARCH点击后触发检索流程。一个结果区域用经典报表或交互式报表显示检索结果。结果里至少包含标题、正文片段、距离、相似度这四列。一个可选的“统计信息”区域显示当前数据量、检索耗时、索引类型。这个信息在演示时特别有说服力。如果你想让页面更生动还可以在结果区域上方放一个条形图把相似度分数可视化。APEX原生图表不需要额外引入前端库配置起来很快。5.2 核心处理逻辑与 SQL 实现关键步骤是点击按钮之后发生的事。我建议用PL/SQL过程来处理先把P1_QUERY里的文本编码成向量然后执行相似检索最后把结果放到一个集合里报表再从集合里取数。编码这一步取决于你选哪种方案。如果外部模型服务已经配好可以这样写declare l_query_vec vector; begin select vector_embedding(text_embedding_model using :P1_QUERY) into l_query_vec from dual; ... end;如果向量是由Python预生成的那就需要另外维护一张“查询词到向量”的映射表。比如准备一些典型的查询样例提前把向量算好存到一张表里页面输入时直接查表获取向量。这对演示来说是够用的但如果你希望允许任意输入还是建议配一个Embedding服务。拿到查询向量之后检索SQL大致长这样select id, title, content, vector_distance(content_vec, :query_vec, COSINE) as distance from doc_vectors order by vector_distance(content_vec, :query_vec, COSINE) fetch first 5 rows only;注意:query_vec是VECTOR类型的绑定变量。在旧版APEX里直接在报表SQL里绑定VECTOR类型变量可能会报类型转换错误我的做法是先在一个PL/SQL过程中把查询向量算好把它存到一个全局临时表或者绑定变量里再让报表SQL去引用。原因很简单APEX交互式报表的SQL绑定变量机制对非标量类型支持不是那么顺滑绕一下能少踩很多坑。如果你想把数据传递给交互式报表可以用APEX_COLLECTION。先创建一个名为SEARCH_RESULT的集合在过程中把结果插入集合报表SQL再从集合里查询。5.3 把距离换算成人能看懂的相似度向量检索算出来的距离对普通用户来说不是很友好。比如余弦距离是0.25大家第一反应是“这个数字算大还是算小”。我更习惯在结果里同时展示“距离”和“相似度”两个指标。如果是余弦距离相似度可以定义为1 - distance。当距离从0到2变化时相似度就是1到-1之间。这样界面上显示“相似度 0.87”观众一眼就能看懂。如果你想让分数落在0到100之间也可以做归一化处理。比如round((1 - vector_distance(content_vec, :query_vec, COSINE)) * 100, 1) as similarity但在语义检索场景距离分布并不一定均匀这种线性映射只是一种简化。演示时它是够用的而且比直接丢一个原始距离要直观得多。5.4 加一个“精确检索”按钮用于对比为了让“近似检索”的效果更突出我还会在页面旁边放一个“精确检索”按钮它执行的是传统SQL的LIKE查询。比如这样select id, title, content from doc_vectors where title like % || :P1_QUERY || % or content like % || :P1_QUERY || %;然后两个按钮放在一起先点“精确检索”让观众看到匹配结果不理想再点“相似检索”展示语义召回的结果。这个对比环节在演示时效果最好也是让观众理解向量检索价值最快的途径。6. 实测对比近似检索与精确检索差在哪6.1 实验设计我在数据集里放了几条不同主题的文档包括慢查询、缓存穿透、APEX开发、连接池调优、网关选型。然后准备了一个测试查询“数据库查询变慢了该怎么办”。用精确检索的SQL去查结果大概率是空集或者只返回标题里带“查询”的那条因为其他几条虽然语义相关但根本没有出现“查询变慢”这样的字面表达。用向量近似检索去查结果是完全不同的。它会优先返回跟“查询变慢”语义最近的文档比如“MySQL慢查询分析”排在第一位“数据库连接池调优”排在第二位因为连接池调优和查询变慢是性能问题里的高度相关话题。6.2 结果解读与演示要点这两类结果的差异直接说明了向量检索和关键词检索的本质区别。传统检索匹配的是“字”向量检索匹配的是“意”。在实际演示时我会把两边的结果截图或者并列展示然后提一个问题“如果你是这个系统的用户哪种结果对你更有用”还有一个细节值得演示当查询输入的是句子而不是关键词时LIKE几乎完全失效但向量检索不受影响。因为模型可以把整个句子的语义浓缩成一个向量再和文档向量计算相似度。这种“以句搜文”的能力是关键词检索很难做到的。顺带说一句演示的时候最好把数据量稍微加大一点比如几千条真实感更强的文档这样近似检索和精确检索的响应时间差异也能展示出来。数据量太小时两种方式的耗时差距不容易被感知说服力会打折扣。7. 常见问题与排查技巧实录7.1 问题速查表这几个问题是我在实际操作中遇到过的整理成表格方便查阅。现象可能原因解决办法创建向量索引时报“ORA-00957”VECTOR列维度不一致或类型不匹配确认插入向量时维度与列定义一致APEX页面绑定VECTOR变量报错报表SQL直接绑定VECTOR类型先在PL/SQL中转为临时表/集合再让报表查询查询结果为空数据表的向量列尚未回填检查是否有UPDATE语句把向量写入检索很慢走全表扫描优化器未选择向量索引使用HINT或检查索引状态相似度结果看起来不对查询和索引的距离算法不一致统一使用COSINEVECTOR_EMBEDDING调用失败外部模型服务网络不通或ACL未配置检查数据库网络访问权限和模型端点配置HNSW索引构建时内存不足参数设置过大调小neighbors和connections7.2 几个值得记住的坑第一个坑是VECTOR列在APEX里的显示问题。直接在交互式报表里选VECTOR列显示出来的可能是一串内部表示完全没法看。解决思路是只把ID、标题、配置和相似度放到报表里不要把原始VECTOR列放进去。第二个坑是Python脚本写回去的向量字符串格式。如果格式不对比如浮点数精度不够或者列表里出现了科学计数法但数据库版本解析不兼容插入时会报错。我的经验是生成向量后统一转成固定小数位数避免使用科学计数法。第三个坑是HNSW索引内存问题。虽然HNSW对中小数据集很友好但如果你把neighbors调到128以上在内存受限的机器上构建索引时可能会遇到内存不足错误。演示环境数据量不大没必要追求极端参数。第四个坑是向量化模型本身的语言问题。如果你用的是sentence-transformers里的英文模型对中文的编码效果会明显偏差。演示中文数据时一定要选支持中文的模型比如paraphrase-multilingual-MiniLM-L12-v2否则向量检索的结果会让人摸不着头脑。这个坑我没有在正文前面提是因为它不属于数据库或APEX的范畴但它对结果质量的影响往往是决定性的。7.3 增强演示效果的几个小优化做演示类程序体验比功能更重要。我会额外加几个小功能第一在页面上显示检索耗时。APEX里可以用DBMS_UTILITY.GET_TIME包住检索逻辑把耗时还原成毫秒显示在结果上方。当观众看到近似检索在几毫秒内完成时对“近似索引的性能优势”会有更直观的感知。第二加上结果条数选择。比如让用户选择Top-3、Top-5、Top-10这能展示不同召回量对结果质量的影响。对教学演示来说这个选项很实用。第三增加一个“随机查询”按钮。预置几条典型的查询样例观众只要点击按钮就能看到不同输入的效果降低了演示时的操作门槛。这也避免了在演示现场手动输入长句容易打错字的问题。第四如果现场网络允许我还会展示把图片向量化之后做以图搜图的例子。本质上和文本检索一样但这种跨模态的演示往往能给观众留下更深的印象。当然了这个属于锦上添花先把文本场景跑通更重要。我个人在实际操作中的体会是做完这个APEX小工具最大的收获倒不是学会了怎么用某个函数而是真正理解了“向量近似检索”这套流程的每一步在干什么。数据准备、向量化、距离算法选择、索引参数、结果展示每个环节都有它自己的坑。而APEX的价值在于它把最复杂的页面交互部分简化掉了让我能把精力全部花在检索本身的逻辑上。最后再分享一个小技巧演示的时候给检索结果加一个“相似度条”会比单纯显示数字效果好得多。因为数字需要观众自己去理解进度条则是一眼就能看懂“这个和那个很像”。一个小小展示方式的改变往往比一大堆技术解释更有说服力。