企业官网建设流程全解析

• 示例工程
• 人工智能
• 大模型

本指南基于当前仓库中的 examples/chromadb/README.md 及其配套教程 Vectordb_with_chroma.ipynb，系统讲解如何用 Gemini API 生成文本嵌入（Embedding）、借助开源 Python 工具 ChromaDB 创建向量数据库，并实现"先检索最相关文档、再交给生成模型作答"的文档问答链路。读完本文，你将掌握自定义 ChromaDB Embedding 函数、批量写入文档向量、近邻检索相关段落，以及将检索结果注入 Prompt 完成 RAG（检索增强生成）问答的完整实战能力。

一、整体思路：Embedding + 向量数据库 + 生成式问答

本教程的核心目标，是用 Gemini API 创建一个向量数据库，并从中检索出与问题最相关的答案。这里选用的向量数据库是 ChromaDB——一个开源的 Python 工具，专门用于创建嵌入数据库。根据教程 Vectordb_with_chroma.ipynb 的 Overview 说明，ChromaDB 支持：

• 存储嵌入向量及其元数据；
• 对文档与查询进行嵌入（Embedding）；
• 在嵌入数据库中进行语义检索。

整个流程可以拆解为三步：先用 Gemini Embedding 模型把文档转换成向量并写入 ChromaDB；再用同样的模型把用户问题向量化，通过近邻搜索找出最相关的文档片段；最后把检索到的片段作为上下文注入 Prompt，交给生成模型产出自然语言答案。这就是典型 RAG 的最小可运行实现。

注意：教程开头明确提示，本 Notebook 需要付费档位的速率限制（rate limits）才能顺利运行，并且当前 Gemini API 仅在部分区域可用。

二、环境准备：安装依赖与导入模块

首先安装 ChromaDB 与 Gemini API 的 Python 库（google-genai SDK）。教程使用%pip魔法命令在 Jupyter/Colab 环境中安装：

%pip install -U -q "google-genai>=2.9.0" chromadb

随后导入本教程所需的模块：

import textwrap import chromadb import numpy as np import pandas as pd from IPython.display import Markdown from chromadb import Documents, EmbeddingFunction, Embeddings

这里Documents、Embeddings、EmbeddingFunction都来自chromadb，它们是后续自定义嵌入函数时使用的类型标注，而numpy与pandas分别用于向量运算和以表格形式查看数据库内容。

三、配置 API Key 与初始化客户端

使用 Gemini API 前必须先取得 API Key，可通过 Google AI Studio 一键创建。在 Colab 中，把 Key 添加到左侧面板"🔑"的 Secrets 管理器，命名为GEMINI_API_KEY。将 Key 交给 SDK 有两种方式：

• 把 Key 写入GEMINI_API_KEY环境变量（SDK 会自动读取）；
• 显式传给genai.Client(api_key=...)。

本教程采用 Colab 的userdata读取 Secret 并初始化客户端：

from google import genai from google.colab import userdata GEMINI_API_KEY = userdata.get('GEMINI_API_KEY') client = genai.Client(api_key=GEMINI_API_KEY)

选择嵌入模型的关键原则

教程强调一个关键点：任何嵌入模型都可以用于本教程，但在真实应用中，一定要选定一个具体模型并持续使用。因为不同模型的输出向量互不兼容，混合使用会导致检索质量不可控。

在google-genaiSDK 中，可以通过列出模型并过滤支持embedContent操作的模型来查看可用的嵌入模型：

for m in client.models.list(): if 'embedContent' in m.supported_actions: print(m.name)

教程运行输出的可用嵌入模型包括：

• models/embedding-001
• models/text-embedding-004
• models/gemini-embedding-exp-03-07
• models/gemini-embedding-exp
• models/gemini-embedding-001

仓库中的 quickstarts/Embeddings.ipynb 还提到，最新的gemini-embedding-2是多模态嵌入模型，可把文本、图片、视频、音频、PDF 映射到同一嵌入空间；而文本场景下gemini-embedding-001仍然可用。本教程的示例采用gemini-embedding-001。

四、准备测试文档数据

教程准备了一小组"Google 汽车使用说明书"风格的文档，用来构建嵌入数据库。三份文档分别介绍：车内气候控制系统（温度、气流、风扇、模式旋钮）、大尺寸触摸屏（导航、娱乐、气候控制）、自动挡换挡（Park / Reverse / Neutral / Drive / Low）。完整内容可直接在 Vectordb_with_chroma.ipynb 中查看，随后将三份文档组装成列表：

documents = [DOCUMENT1, DOCUMENT2, DOCUMENT3]

这类语料的特点是主题集中、句式规整，非常适合用来直观验证"语义相近的查询能命中对应文档"。

五、创建嵌入数据库：自定义 Embedding 函数

ChromaDB 支持自定义嵌入函数（custom embedding function），教程据此实现了一个调用 Gemini API 的GeminiEmbeddingFunction。

5.1 关于 gemini-embedding-001 的新参数

在调用gemini-embedding-001时，需要了解两个新增参数：task_type（任务类型）以及仅当task_type=RETRIEVAL_DOCUMENT时才有效的可选title。这两个参数只适用于最新的嵌入模型，task_type的取值与含义如下表：

补充说明：在 quickstarts/Embeddings.ipynb 的 "Using task_type" 章节中明确指出，task_type参数仅对gemini-embedding-001生效；对于gemini-embedding-2，该参数不受支持，文本场景下应把任务指令直接写进 prompt。

5.2 实现 GeminiEmbeddingFunction

自定义函数继承自 ChromaDB 的EmbeddingFunction，实现__call__方法，接收Documents类型的输入并返回Embeddings（向量列表）：

from google.genai import types class GeminiEmbeddingFunction(EmbeddingFunction): def __call__(self, input: Documents) -> Embeddings: EMBEDDING_MODEL_ID = "gemini-embedding-001" # @param ["text-embedding-004", "gemini-embedding-001"] {"allow-input": true, "isTemplate": true} title = "Custom query" response = client.models.embed_content( model=EMBEDDING_MODEL_ID, contents=input, config=types.EmbedContentConfig( task_type="retrieval_document", title=title ) ) return response.embeddings[0].values

代码要点：

• client.models.embed_content是 google-genai SDK 的嵌入调用入口，config=types.EmbedContentConfig(...)用来携带task_type与title；
• 文档写入场景使用retrieval_document任务类型，让模型生成的向量针对"文档入库"进行优化；
• 返回response.embeddings[0].values，即该批次文档对应的嵌入向量值。

顺带一提，教程的运行输出中出现了 ChromaDB 的弃用警告（DeprecationWarning）：GeminiEmbeddingFunction没有实现__init__，这在未来版本中将成为必需。这意味着在升级 ChromaDB 后，建议在类中显式补充__init__方法以保证兼容性。

5.3 创建 collection 并写入文档

接下来编写create_chroma_db函数：实例化一个 Chroma 客户端，通过create_collection创建集合（collection）——collection 就是存放嵌入、文档和任意元数据的地方，前面定义的嵌入函数作为embedding_function参数传入；随后用add方法逐条写入文档：

def create_chroma_db(documents, name): chroma_client = chromadb.Client() db = chroma_client.create_collection( name=name, embedding_function=GeminiEmbeddingFunction() ) for i, d in enumerate(documents): db.add( documents=d, ids=str(i) ) return db

调用该函数创建名为google-car-db的数据库：

# Set up the DB db = create_chroma_db(documents, "google-car-db")

这里ids使用字符串形式的序号（"0"、"1"、"2"）作为每条文档的唯一标识。

5.4 验证数据是否写入成功

用db.get(include=['documents', 'embeddings'])取回已入库的内容，并用 pandas 展示（嵌入向量截断显示以免输出过长）：

sample_data = db.get(include=['documents', 'embeddings']) df = pd.DataFrame({ "IDs": sample_data['ids'][:3], "Documents": sample_data['documents'][:3], "Embeddings": [str(emb)[:50] + "..." for emb in sample_data['embeddings'][:3]] # Truncate embeddings }) df

输出结果是一张三行三列的表格（IDs / Documents / Embeddings），可以看到每条文档都对应一段浮点数向量，例如[ 0.00971627 -0.00177013 0.00590323 ...]，证明嵌入已成功生成并入库。

六、语义检索：找出与问题最相关的文档

db是 Chroma 的 collection 对象，可以直接对它调用query方法执行近邻搜索（nearest neighbors search），找出与查询语义最接近的嵌入或文档。教程封装了get_relevant_passage函数：

def get_relevant_passage(query, db): passage = db.query(query_texts=[query], n_results=1)['documents'][0][0] return passage

n_results=1表示只返回最相似的一条结果；['documents'][0][0]则依次取出"第一条结果、第一个文档列表中的第一项"。用查询"touch screen features"测试：

# Perform embedding search passage = get_relevant_passage("touch screen features", db) Markdown(passage)

返回的正是介绍触摸屏功能的 DOCUMENT2——注意查询文本并没有包含"导航""音乐"等原文关键词，却能命中语义相关的文档，这正是向量检索相对关键词匹配的优势所在。

七、构造 Prompt 并调用生成模型回答

找到相关段落之后，下一步就是把它做成 Prompt 交给 Gemini 生成模型。make_prompt函数负责把检索到的段落清洗（去除引号与换行）后，嵌入到一段固定的指令模板中：

def make_prompt(query, relevant_passage): escaped = relevant_passage.replace("'", "").replace('"', "").replace("\n", " ") prompt = (""" You are a helpful and informative bot that answers questions using text from the reference passage included below. Be sure to respond in a complete sentence, being comprehensive, including all relevant background information. However, you are talking to a non-technical audience, so be sure to break down complicated concepts and strike a friendly and converstional tone. If the passage is irrelevant to the answer, you may ignore it. QUESTION: '{query}' PASSAGE: '{relevant_passage}' ANSWER: """).format(query=query, relevant_passage=escaped) return prompt

模板的设计思路很明确：让模型只用参考段落作答、面向非技术读者给出完整而友好的解释，同时允许在段落与问题无关时忽略它。传入示例问题并生成完整 Prompt：

query = "How do you use the touchscreen in the Google car?" prompt = make_prompt(query, passage) Markdown(prompt)

最后用generate_content方法让模型基于该 Prompt 生成回答：

MODEL_ID = "gemini-3.8-flash" # @param ["gemini-3.1-pro-preview", "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input": true, "isTemplate": true} answer = client.models.generate_content( model = MODEL_ID, contents = prompt ) Markdown(answer.text)

教程中的实际输出演示了完整的 RAG 效果：模型基于检索到的触摸屏段落，用通俗、友好的口吻解释了"轻触图标即可使用导航、音乐、气候控制等功能"——既没有照搬原文，也没有超出检索上下文编造内容。

八、深入学习与仓库内相关资源

本教程展示了把 Embedding 应用于向量数据库的典型模式。如果想继续深入了解，仓库中还有大量相关资源：

• quickstarts/Embeddings.ipynb：Embedding 入门指南，涵盖多模态嵌入（文本/图片/音频/视频/PDF）、批量嵌入、output_dimensionality降维、基于余弦相似度的句子相似度分析，以及用task_type构建 RAG 的完整示例（find_best_passage+ 生成式回答）；
• examples/Talk_to_documents_with_embeddings.ipynb 与 examples/document_search.ipynb：文档级问答与搜索实践；
• examples/Search_reranking_using_embeddings.ipynb：用 Embedding 对 Wikipedia 搜索结果重排序；
• examples/Anomaly_detection_with_embeddings.ipynb：用 Embedding 检测数据集中的离群点；
• examples/Classify_text_with_embeddings.ipynb：基于 Embedding 训练文本分类器；
• 向量数据库生态示例：examples/langchain、examples/llamaindex、examples/qdrant、examples/weaviate。

九、小结

本文完整复现了 ChromaDB 与 Gemini API 组合构建向量数据库问答系统的最小闭环：安装依赖 → 配置 Key → 定义自定义嵌入函数 → 创建 collection 入库 → 近邻检索 → 构造 Prompt → 生成回答。需要记住的实践要点包括：选定并固定一个嵌入模型、文档入库使用retrieval_document任务类型、查询向量化后通过db.query做近邻搜索、最终回答严格锚定检索上下文。这套模式可以直接迁移到 FAQ 机器人、企业知识库问答等真实场景，是上手 RAG 的最佳起点。

• 示例工程
• 人工智能
• 大模型