大家好呀，我是小米，31岁，程序员，爱分享技术也爱喝奶茶。最近在搞一个新项目的时候，团队决定引入 Spring AI + Azure OpenAI 向量模型（Embedding） ，刚开始我一脸懵逼，毕竟 Azure 的生态和 OpenAI API 有点差别，Spring AI 的封装又有点“黑魔法”。结果我折腾了几天，终于把全套踩坑经验总结出来啦！今天就给大家从头到尾扒一遍，希望能帮到在面试、开发中正好用到这块的朋友们。
Azure OpenAI 向量模型是个啥？
我第一次接触“向量模型（Embedding）”这个词的时候，还以为是数学课本里的线性代数，满脑子都是矩阵相乘。但实际上，在 自然语言处理（NLP） 里，Embedding 就是把文字转化为一组稠密的向量（数字数组），这样机器才能理解语义。
举个例子：
- “猫” 和 “狗” 在语义空间里可能很接近，向量的余弦相似度也很高。
- 但 “猫” 和 “火箭” 就差得远，向量差异也大。
Azure OpenAI 向量模型 的核心就是提供这种 高质量语义向量，常见用途有：
- 搜索增强（RAG） —— 先用 Embedding 生成向量，再存进向量数据库（比如 Pinecone、Milvus、Redis Search），之后问问题时做语义检索。
- 文本聚类/推荐 —— 类似的文本会聚到一起，比如新闻推荐、相似问题检索。
- 分类 —— 用向量表示后再丢给分类模型，准确度更高。
而 Spring AI 就是帮我们屏蔽了大部分底层 HTTP 调用逻辑，只需要写一点配置，就能用 Azure OpenAI 的向量能力，舒服！
使用前的先决条件
想要跑通 Spring AI + Azure OpenAI Embedding，你得准备好几样东西：
- Azure 账号 —— 没 Azure 账号你就别想了，得先去 Azure 门户注册。
- Azure OpenAI 资源 —— 在 Azure 门户创建 OpenAI 服务，选择要用的区域（常见 East US、West Europe 等）。
- 向量模型部署 —— 在 Azure OpenAI 服务里，部署一个 Embedding 模型（比如 text-embedding-3-small 或 text-embedding-3-large）。
- Spring Boot 项目 —— 至少得有个能跑 Spring Boot 3.x 的项目环境，建议配合 Gradle/Maven。
- JDK 17+ —— Spring AI 要求 JDK17 起步。
如果这些条件都搞定了，接下来的配置就水到渠成了。
Azure API 密钥和终结点
Azure 的 OpenAI 服务不像 OpenAI 官方直接给个 key 就能用，它需要两个关键配置：
- API Key —— 在 Azure 门户里找到你创建的 OpenAI 资源，点击“Keys and Endpoints”，就能拿到 KEY1 和 KEY2，随便用一个。
- Endpoint —— 形如：your-resource-name.openai.azure.com/
这两个配置是必须的，Spring AI 会依赖它们去拼接请求。
OpenAI 密钥
这里容易踩坑。Spring AI 同时支持：
- Azure OpenAI
- OpenAI 官方 API
如果你写配置时只填了 openai.api-key，那默认会走 OpenAI 的官方地址；如果要走 Azure，就得写上 endpoint 和 deployment 名称。
也就是说，Azure 的配置多一步，千万别偷懒。
自动配置（Spring AI 的魔法）
Spring AI 在 starter 里给我们提供了自动配置，理论上只要 application.yml 配好，就能直接注入 EmbeddingModel 来用。
典型的配置是这样的：
这里的 deployment-name 就是你在 Azure Portal 里给模型起的名字。
Embedding 属性表格
为了让大家更直观，我整理了常用的 Embedding 配置属性表：
有了这个表，就不用一遍遍去翻文档啦！
运行时选项
除了配置文件，我们还可以在运行时动态设置一些参数。
比如：
- 选择不同的向量模型 —— 有时候要在 small 和 large 之间切换，可以在代码里指定。
- 超时/代理 —— Spring AI 底层还是走 WebClient，可以在 RestClient 里设置超时、代理。
- 日志调试 —— 建议打开 DEBUG 日志，能看到 Spring AI 拼的请求体和返回体，方便排错。
示例代码
给大家上点代码感受下（伪代码，但能跑）：
只要配置没问题，启动 Spring Boot 项目后访问：
你就能得到一大串浮点数向量，妥妥的语义表示！
手动配置
如果你嫌弃自动配置“黑箱”，那也可以自己手动创建 AzureOpenAiEmbeddingModel。
这样就完全由你掌控，灵活度更高。
写在最后
折腾 Azure OpenAI Embedding 的这几天，我最大的感受就是：
Spring AI 真香。它把底层复杂的 HTTP 请求、签名、模型参数都封装好了，配置一写就能跑起来，代码层面几乎不用操心。
如果你正好在准备面试，这块也能当亮点吹：
- 会用 Azure OpenAI Embedding
- 熟悉 Spring AI 自动配置和手动配置
- 知道如何跑通 RAG 流程
预祝大家都能顺利搞定项目，面试拿下大厂 offer ！
END
我是小米，一个喜欢分享技术的31岁程序员。如果你喜欢我的文章，欢迎关注我的微信公众号“软件求生”，获取更多技术干货！
