gemma-3-12b-it实战手册：使用Ollama Embeddings API做图文向量联合检索

1. 引言：为什么需要图文联合检索？

想象一下这样的场景：你有一个包含大量图片和文字说明的数据库，想要快速找到与某个查询相关的所有内容。传统的文本搜索只能匹配文字，图片搜索只能匹配视觉特征，而图文联合检索可以同时理解文字和图片的含义，找到最相关的结果。

这就是gemma-3-12b-it的强项。作为Google推出的多模态模型，它不仅能理解文字，还能看懂图片，更厉害的是可以通过Ollama提供的Embeddings API将图文内容转换为向量表示，实现高效的相似度检索。

本文将手把手教你如何使用Ollama部署的gemma-3-12b-it模型，通过Embeddings API实现图文向量联合检索，让你快速掌握这项实用技术。

2. 环境准备与模型部署

2.1 安装Ollama

首先确保你的系统已经安装了Ollama。如果还没有安装，可以通过以下命令快速安装：

# Linux/macOS安装命令
curl -fsSL https://ollama.ai/install.sh | sh

# Windows安装（需要管理员权限）
winget install Ollama.Ollama

安装完成后，启动Ollama服务：

ollama serve

2.2 拉取gemma-3-12b-it模型

gemma-3-12b-it是Gemma 3系列的12B参数指令调优版本，支持多模态输入。使用以下命令拉取模型：

ollama pull gemma3:12b

这个命令会自动下载模型文件，文件大小约12GB，下载时间取决于你的网络速度。

2.3 验证模型安装

模型下载完成后，可以通过简单的交互测试验证是否安装成功：

ollama run gemma3:12b

然后在提示符后输入测试问题，比如"你好"，如果得到正常回复，说明模型安装成功。

3. 理解Embeddings API的工作原理

3.1 什么是向量嵌入？

向量嵌入（Embeddings）是将文本、图片等非结构化数据转换为数值向量的技术。这些向量能够捕捉数据的语义信息，相似的内容在向量空间中距离更近。

gemma-3-12b-it的多模态能力让它能够同时处理文本和图像，并为两者生成统一的向量表示，这是实现图文联合检索的基础。

3.2 Ollama Embeddings API接口

Ollama提供了简单的HTTP API来获取嵌入向量：

curl http://localhost:11434/api/embeddings -d '{
  "model": "gemma3:12b",
  "prompt": "你要转换为向量的文本或图片描述"
}'

API会返回一个JSON响应，包含生成的向量数据。

3.3 图文向量的统一表示

gemma-3-12b-it的厉害之处在于，无论是文字还是图片，它都能生成相同维度的向量（通常是4096维），这样我们就可以在同一个向量空间中进行相似度计算。

4. 实战：构建图文检索系统

4.1 准备示例数据

我们先创建一个简单的示例数据集，包含图片和对应的文字描述：

sample_data = [
    {
        "id": 1,
        "image_path": "cat.jpg",
        "text_description": "一只橘猫在沙发上睡觉"
    },
    {
        "id": 2, 
        "image_path": "dog.jpg",
        "text_description": "金毛犬在公园里玩飞盘"
    },
    {
        "id": 3,
        "image_path": "landscape.jpg",
        "text_description": "夕阳下的山水风景"
    }
]

4.2 生成嵌入向量

接下来我们编写Python代码来生成所有数据的嵌入向量：

import requests
import json
import numpy as np

def get_embedding(content, is_image=False):
    """
    获取文本或图片的嵌入向量
    """
    url = "http://localhost:11434/api/embeddings"
    
    if is_image:
        # 对于图片，我们需要先将其转换为base64编码
        # 这里简化处理，实际使用时需要添加图片处理逻辑
        prompt = f"描述这张图片：{content}"
    else:
        prompt = content
    
    payload = {
        "model": "gemma3:12b",
        "prompt": prompt
    }
    
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        return response.json()["embedding"]
    else:
        raise Exception(f"获取嵌入向量失败：{response.text}")

# 为所有数据生成嵌入向量
embeddings = []
for item in sample_data:
    # 生成文本描述的嵌入
    text_embedding = get_embedding(item["text_description"])
    
    # 生成图片的嵌入（实际使用时需要处理图片文件）
    image_embedding = get_embedding(item["image_path"], is_image=True)
    
    # 合并文本和图片向量（简单平均）
    combined_embedding = np.mean([text_embedding, image_embedding], axis=0)
    
    embeddings.append({
        "id": item["id"],
        "embedding": combined_embedding.tolist()
    })

4.3 实现检索功能

有了嵌入向量后，我们可以实现检索功能：

from sklearn.metrics.pairwise import cosine_similarity

def search(query, embeddings_db, top_k=3):
    """
    根据查询语句检索最相关的项目
    """
    # 获取查询语句的嵌入向量
    query_embedding = get_embedding(query)
    query_embedding = np.array(query_embedding).reshape(1, -1)
    
    # 计算相似度
    similarities = []
    for item in embeddings_db:
        item_embedding = np.array(item["embedding"]).reshape(1, -1)
        similarity = cosine_similarity(query_embedding, item_embedding)[0][0]
        similarities.append((item["id"], similarity))
    
    # 按相似度排序并返回top_k结果
    similarities.sort(key=lambda x: x[1], reverse=True)
    return similarities[:top_k]

# 示例检索
results = search("找一张宠物的照片", embeddings)
print("检索结果：", results)

5. 高级应用与优化技巧

5.1 批量处理优化

当处理大量数据时，逐个生成嵌入向量效率很低。我们可以使用批量处理：

def batch_get_embeddings(texts, batch_size=10):
    """
    批量获取嵌入向量，提高效率
    """
    all_embeddings = []
    
    for i in range(0, len(texts), batch_size):
        batch = texts[i:i+batch_size]
        batch_embeddings = []
        
        for text in batch:
            embedding = get_embedding(text)
            batch_embeddings.append(embedding)
        
        all_embeddings.extend(batch_embeddings)
    
    return all_embeddings

5.2 向量数据库集成

对于生产环境，建议使用专业的向量数据库：

# 使用Chroma向量数据库的示例
import chromadb

# 创建向量数据库客户端
client = chromadb.Client()

# 创建集合
collection = client.create_collection("image_text_search")

# 添加嵌入向量
for i, item in enumerate(embeddings):
    collection.add(
        ids=[str(item["id"])],
        embeddings=[item["embedding"]],
        metadatas=[{"type": "image_text"}]
    )

# 查询
results = collection.query(
    query_embeddings=[query_embedding],
    n_results=3
)

5.3 多模态权重调整

根据实际需求，你可以调整文本和图片在联合向量中的权重：

def get_weighted_embedding(text, image_path, text_weight=0.5, image_weight=0.5):
    """
    根据权重生成加权后的联合向量
    """
    text_embedding = get_embedding(text)
    image_embedding = get_embedding(image_path, is_image=True)
    
    weighted_embedding = (np.array(text_embedding) * text_weight + 
                         np.array(image_embedding) * image_weight)
    
    return weighted_embedding.tolist()

6. 实际应用场景

6.1 电商商品搜索

图文联合检索特别适合电商场景，用户可以用文字描述想要找的商品，系统同时匹配商品图片和文字描述：

# 电商商品检索示例
def search_products(query, product_embeddings):
    """
    电商商品搜索
    """
    results = search(query, product_embeddings)
    
    # 返回商品信息而不仅仅是ID
    product_results = []
    for product_id, similarity in results:
        product_info = get_product_info(product_id)  # 假设的函数
        product_info["similarity"] = similarity
        product_results.append(product_info)
    
    return product_results

6.2 内容管理系统

对于拥有大量图文内容的企业，可以构建智能内容检索系统：

class ContentSearchSystem:
    def __init__(self):
        self.embeddings_db = []
        self.content_db = {}  # 存储完整内容信息
    
    def add_content(self, content_id, text, image_path=None):
        """
        添加内容到检索系统
        """
        embedding = get_weighted_embedding(text, image_path)
        
        self.embeddings_db.append({
            "id": content_id,
            "embedding": embedding
        })
        
        self.content_db[content_id] = {
            "text": text,
            "image_path": image_path
        }
    
    def search_content(self, query, top_k=5):
        """
        搜索相关内容
        """
        results = search(query, self.embeddings_db, top_k)
        
        detailed_results = []
        for content_id, similarity in results:
            content_info = self.content_db[content_id].copy()
            content_info["similarity"] = similarity
            detailed_results.append(content_info)
        
        return detailed_results

6.3 学术文献检索

研究人员可以使用这个系统检索相关的学术论文和图表：

# 学术文献检索示例
def search_academic_papers(query, papers_embeddings):
    """
    检索学术论文，同时匹配文本内容和图表
    """
    results = search(query, papers_embeddings)
    
    # 添加相关性评分和过滤阈值
    filtered_results = [
        (paper_id, score) for paper_id, score in results if score > 0.7
    ]
    
    return filtered_results

7. 性能优化与最佳实践

7.1 缓存机制

为了提升性能，可以实现嵌入向量缓存：

from functools import lru_cache

@lru_cache(maxsize=1000)
def cached_get_embedding(content, is_image=False):
    """
    带缓存的嵌入向量获取函数
    """
    return get_embedding(content, is_image)

7.2 异步处理

对于高并发场景，使用异步处理提高性能：

import aiohttp
import asyncio

async def async_get_embedding(session, content):
    """
    异步获取嵌入向量
    """
    url = "http://localhost:11434/api/embeddings"
    payload = {
        "model": "gemma3:12b",
        "prompt": content
    }
    
    async with session.post(url, json=payload) as response:
        if response.status == 200:
            data = await response.json()
            return data["embedding"]
        else:
            raise Exception("获取嵌入向量失败")

async def batch_async_embeddings(contents):
    """
    批量异步获取嵌入向量
    """
    async with aiohttp.ClientSession() as session:
        tasks = [async_get_embedding(session, content) for content in contents]
        return await asyncio.gather(*tasks)

7.3 错误处理与重试机制

添加健壮的错误处理和重试机制：

import time
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def robust_get_embedding(content):
    """
    带有重试机制的嵌入向量获取
    """
    try:
        return get_embedding(content)
    except Exception as e:
        print(f"获取嵌入向量失败：{e}")
        raise

8. 总结

通过本文的实战指南，你应该已经掌握了使用gemma-3-12b-it和Ollama Embeddings API构建图文向量联合检索系统的方法。这种技术的强大之处在于能够真正理解多模态内容的语义，而不仅仅是关键词匹配。

关键要点回顾：

• gemma-3-12b-it是多模态模型，能同时处理文本和图像
• Ollama提供了简单的API来获取嵌入向量
• 通过向量相似度计算可以实现精准的图文检索
• 在实际应用中需要考虑性能优化和错误处理

下一步学习建议：

1. 尝试不同的向量加权策略，找到最适合你场景的配置
2. 探索专业的向量数据库，如Chroma、Pinecone或Weaviate
3. 考虑添加用户反馈机制，持续优化检索质量
4. 实验不同的相似度计算算法，如欧几里得距离、曼哈顿距离等

图文联合检索是AI应用中的一个重要方向，掌握了这项技术，你就能构建更加智能和用户友好的搜索系统。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。