使用 LiteLLM Terraform Provider 的 litellm_vector_store 数据源：读取既有向量库、打通 RAG 资源编排与监控审计

本篇技术指南围绕官方 Terraform Provider（terraform-provider-litellm）中的 litellm_vector_store **数据源（Data Source）**展开，讲解如何用声明式 IaC 方式读取 LiteLLM 系统中已存在的向量存储（Vector Store）信息，并将其用于跨配置引用、条件化资源创建、批量监控与合规审计等场景。读完本文，你将掌握该数据源的全部入参与导出属性、底层 API 调用链（POST /vector_store/info）以及它与 litellm_vector_store 资源、litellm_credential 数据源、litellm_model 资源组合使用的完整姿势。

背景：为什么要用数据源读取向量存储

LiteLLM Proxy 本身是一套面向 100+ 大模型厂商的统一 AI 网关，其内置的向量存储（Vector Store）能力用于支撑语义检索与 RAG（检索增强生成）等场景，官方支持 AWS Bedrock Knowledge Bases、OpenAI Vector Stores、Azure Vector Stores、Vertex AI RAG Engine 与 PG Vector 等后端（参见 vector_store 资源文档）。

在 Terraform 体系中存在两类管理入口：

• Resource（资源）：负责在 LiteLLM 中创建、更新、删除向量存储，是可写的声明式对象；
• Data Source（数据源）：只负责"读取"，把 Terraform 外部（或本次配置之外）已经存在的向量存储信息导入到 state 中供引用。

litellm_vector_store 数据源对应的正是后者。文档开篇明确指出其语义（data-sources/vector_store.md）：Retrieves information about an existing LiteLLM vector store——它允许你在 Terraform 配置里引用那些"由其他 Terraform 配置创建的、或完全在 Terraform 之外创建"的向量库，从而避免重复定义与漂移。该数据源与同名资源在 Provider 中一并注册（见 provider.go），资源侧重生命周期管理，数据源侧重只读引用，二者 ID 体系一致，均为 LiteLLM 分配的唯一 vector_store_id。

数据源基础用法：按 ID 检索并输出

该数据源的 Schema 非常收敛，入参只有一个：vector_store_id（必填），是 LiteLLM 系统为向量存储分配的全局唯一标识符。

最基础的用法是直接按 ID 检索，并在 output 中暴露关键信息：

# Retrieve an existing vector store by ID
data "litellm_vector_store" "existing_store" {
  vector_store_id = "vs-12345"
}

# Use the vector store information in outputs
output "vector_store_info" {
  value = {
    name        = data.litellm_vector_store.existing_store.vector_store_name
    provider    = data.litellm_vector_store.existing_store.custom_llm_provider
    created_at  = data.litellm_vector_store.existing_store.created_at
  }
}

需要注意的语义细节：

• 若指定的 vector_store_id 在 LiteLLM 系统中不存在，该数据源的读取会直接报错（文档 Notes 中明确说明 "The data source will fail if the specified vector store ID does not exist"），这与同名资源读取时的"发现不存在即清空 ID、静默退出"行为不同，两者对缺失对象的容错策略需要区分使用（源码对比见下节"错误处理"）。
• 所有导出属性反映的是读取时刻 LiteLLM 系统中该向量存储的当前状态，即文档所强调的 "All computed attributes reflect the current state"。
• 需要与动态变量配合时，vector_store_id 完全支持来自 var.*、terraform.tfvars 或上游资源输出的引用（data.litellm_vector_store.shared_store.vector_store_id 亦可作为其它资源的输入）。

参数与属性完整参考

Argument Reference

参数	必填	类型	说明
vector_store_id	Required	string	要读取的向量存储在 LiteLLM 中的唯一标识

对应实现位于 data_source_vector_store.go：Schema 中 vector_store_id 被声明为 Type: schema.TypeString, Required: true。

Attributes Reference

除入参本身外，数据源导出如下只读属性：

属性	类型	说明
vector_store_name	string	向量存储的名称
custom_llm_provider	string	该向量存储所使用的大模型/向量服务供应商（如 openai、bedrock、azure、vertex_ai、pgvector 等）
vector_store_description	string	向量存储的描述
vector_store_metadata	map(string)	与该向量存储关联的元数据键值对
litellm_credential_name	string	该向量存储所用 LiteLLM 凭据的名称
litellm_params	map(string)	额外的 LiteLLM 参数集合
created_at	string	向量存储的创建时间戳
updated_at	string	向量存储的最后更新时间戳

从源码看，上述字段与 data_source_vector_store.go 中的 Schema 定义一一对应：字符串属性均为 Computed，而 vector_store_metadata 与 litellm_params 两个 map 属性的元素类型均为 TypeString（即 map(string)，[E404 提示] 嵌套值需以字符串形式表达）。请求与响应的字段契约还可在 types.go 中确认：VectorStoreResponse 使用 vector_store_id / custom_llm_provider / vector_store_name / vector_store_description / vector_store_metadata / created_at / updated_at / litellm_credential_name / litellm_params 这些 JSON 字段回传，与文档属性表完全一致。

进阶用法一：跨配置引用（Cross-Reference）

向量库往往由专有的 Terraform 工作区（或外部系统）负责创建，而推理/路由配置则由另一套配置管理。此时可以用数据源做桥接——读取既有向量库关联的凭据名，再把它喂给同一供应商的模型资源：

# Get vector store info to reference in other configurations
data "litellm_vector_store" "shared_store" {
  vector_store_id = var.shared_vector_store_id
}

# Create a model that might use the same credential as the vector store
data "litellm_credential" "store_credential" {
  credential_name = data.litellm_vector_store.shared_store.litellm_credential_name
}

resource "litellm_model" "embedding_model" {
  model_name          = "embedding-model"
  custom_llm_provider = "openai"
  base_model          = "text-embedding-ada-002"
  mode                = "embedding"

  additional_litellm_params = {
    credential_name = data.litellm_credential.store_credential.credential_name
  }
}

这里的核心链路是数据源串联数据源：litellm_vector_store 导出 litellm_credential_name，其值可以直接作为 litellm_credential 数据源的查询键（该数据源文档见 data-sources/credential.md），最终把同一套凭据绑定到 embedding 模型上，保证"读写同一个知识库"时凭证一致。这种间接引用的好处是：底层向量库被谁创建、何时创建都不再重要，Terraform 始终以当前实际状态为准。

进阶用法二：配置校验与条件化预检（Validation）

数据源的另一个典型职责是"预检"。可以在任何依赖资源创建之前，先读取目标向量存储，再用 count 等机制做条件判断，让依赖资源只有在向量库确实按预期配置时才被创建：

# Verify vector store exists and get its configuration
data "litellm_vector_store" "production_store" {
  vector_store_id = "production-vector-store-id"
}

# Create resources only if the vector store is properly configured
resource "litellm_model" "rag_model" {
  count = data.litellm_vector_store.production_store.custom_llm_provider == "pinecone" ? 1 : 0

  model_name          = "rag-enabled-model"
  custom_llm_provider = "openai"
  base_model          = "gpt-4"
  mode                = "chat"

  additional_litellm_params = {
    vector_store_id = data.litellm_vector_store.production_store.vector_store_id
  }
}

该模式借用了 Terraform 的依赖图特性：litellm_model 通过 count 与 additional_litellm_params 显式引用数据源输出，Terraform 会先完成数据源的读取再决定资源个数。若向量库不存在，数据源读取直接失败并阻断整个 plan/apply——这正是将"配置漂移"在 IaC 层提前暴露的做法。同时注意：上面的表达式同时演示了把读取到的 vector_store_id 原样写回下游模型的 additional_litellm_params，实现数据驱动配置。

进阶用法三：批量监控与状态导出（Monitoring）

当需要监控多个向量存储、并把状态同步给外部监控系统时，可以借助 for_each 批量实例化数据源，再汇总成一张状态 map 输出：

# Get vector store details for monitoring and alerting
data "litellm_vector_store" "monitored_stores" {
  for_each = toset(var.vector_store_ids)

  vector_store_id = each.value
}

# Output store information for monitoring systems
output "vector_store_status" {
  value = {
    for k, v in data.litellm_vector_store.monitored_stores : k => {
      name         = v.vector_store_name
      provider     = v.custom_llm_provider
      created_at   = v.created_at
      updated_at   = v.updated_at
      metadata     = v.vector_store_metadata
    }
  }
}

这里 for_each = toset(var.vector_store_ids) 对每个 ID 生成一个数据源实例，k 即集合中的 ID 字符串，v 为该实例的全部导出属性。收集到的 vector_store_status 是一个 map 结构，天然适合被输出给日志采集、告警机器人或下游数据管道消费。同理也可结合 count、terraform_data 等对版本化监控做更多扩展。

典型使用场景（Common Use Cases）

1. 跨栈引用（Cross-Stack References）

知识库 ID 以变量形式从外层传入，读取后复用其凭据创建推理模型：

data "litellm_vector_store" "shared_knowledge_base" {
  vector_store_id = var.knowledge_base_id
}

# Use the same credential for consistency
resource "litellm_model" "knowledge_model" {
  model_name          = "knowledge-retrieval-model"
  custom_llm_provider = "openai"
  base_model          = "gpt-4"

  additional_litellm_params = {
    vector_store_credential = data.litellm_vector_store.shared_knowledge_base.litellm_credential_name
  }
}

2. 配置校验（Configuration Validation）

读取向量库后，用 locals 固化判断结果，再决定是否为特定供应商创建优化模型：

data "litellm_vector_store" "target_store" {
  vector_store_id = var.target_vector_store_id
}

# Ensure the vector store uses the expected provider
locals {
  is_pinecone_store = data.litellm_vector_store.target_store.custom_llm_provider == "pinecone"
}

resource "litellm_model" "pinecone_optimized_model" {
  count = local.is_pinecone_store ? 1 : 0

  model_name          = "pinecone-optimized"
  custom_llm_provider = "openai"
  base_model          = "text-embedding-ada-002"
  mode                = "embedding"
}

3. 基于元数据的逻辑（Metadata-Based Logic）

利用 vector_store_metadata 中记录的环境标签，让不同环境各得其所——生产环境用高规格模型，开发环境用低成本模型：

data "litellm_vector_store" "environment_store" {
  vector_store_id = var.vector_store_id
}

# Create different resources based on environment metadata
resource "litellm_model" "production_model" {
  count = lookup(data.litellm_vector_store.environment_store.vector_store_metadata, "environment", "") == "production" ? 1 : 0

  model_name          = "production-rag-model"
  custom_llm_provider = "openai"
  base_model          = "gpt-4"
  mode                = "chat"
}

resource "litellm_model" "development_model" {
  count = lookup(data.litellm_vector_store.environment_store.vector_store_metadata, "environment", "") == "development" ? 1 : 0

  model_name          = "development-rag-model"
  custom_llm_provider = "openai"
  base_model          = "gpt-3.5-turbo"
  mode                = "chat"
}

提示：lookup(map, key, default) 返回的是 map 值。由于该数据源的 vector_store_metadata 是 map(string)，第三参数 "" 作为缺省默认值即可安全参与字符串比较。元数据本身在创建向量库时通过资源的 vector_store_metadata 写入（参见 vector_store 资源文档 中的示例，如 environment = "production"、purpose = "file-search"），数据源侧读出后用于派生逻辑。

4. 审计与合规（Audit and Compliance）

对一组合规向量库做只读盘点，生成可交付的合规报告输出：

data "litellm_vector_store" "compliance_stores" {
  for_each = toset(var.compliance_vector_store_ids)

  vector_store_id = each.value
}

# Generate compliance report
output "compliance_report" {
  value = {
    for k, v in data.litellm_vector_store.compliance_stores : k => {
      store_name   = v.vector_store_name
      provider     = v.custom_llm_provider
      credential   = v.litellm_credential_name
      created_date = v.created_at
      last_updated = v.updated_at
      metadata     = v.vector_store_metadata
    }
  }
}

由于数据源只读不写，此场景非常适合由 CI 定期执行 terraform plan/apply -refresh-only（或配合 terraform output），在不触碰任何运行时对象的前提下产出"谁在用什么凭据、连接哪个供应商、何时创建/更新"的审计快照。

底层实现：数据源是如何读到向量库的

把视角切到 Provider 源码，可以精确还原数据源的单次读取链路：

1. Schema 定义：data_sourceLiteLLMVectorStore() 返回 *schema.Resource，只注册了 Read 回调 dataSourceLiteLLMVectorStoreRead，Schema 中 vector_store_id 为唯一必填输入（data_source_vector_store.go）。
2. 发起请求：读取回调中构造 VectorStoreInfoRequest{VectorStoreID: ...}，向 LiteLLM Proxy 发送 POST /vector_store/info（data_source_vector_store.go）。请求结构体的 JSON 字段契约见 types.go。
3. 统一响应处理：handleVectorStoreAPIResponse 负责把 HTTP 响应解析进 VectorStoreResponse（utils.go）。该函数专门针对向量存储接口做了错误归一化：HTTP 404 或 LiteLLM 返回的 "vector store not found" 错误细节都会被折叠成统一的 vector_store_not_found 错误标记。
4. 错误与状态回填：对数据源而言，404 / vector_store_not_found 会直接以 vector store '%s' not found 报错退出（而不是像资源 Read 那样调用 d.SetId("") 静默失联，对比见 resource_vector_store_crud.go）。读取成功则依次执行 d.SetId(vectorStoreResp.VectorStoreID) 并把八个计算属性逐一 d.Set 进 state（data_source_vector_store.go）。

从 Proxy 侧看，/vector_store/new、/vector_store/delete、/vector_store/info（以及 update 等）都是在 management_endpoints.py 中注册的受保护管理端点；而真正的后端能力由 litellm/vector_stores/main.py 按 custom_llm_provider 分发实现，不同供应商的 create / info / search / delete 支持度各不相同，Provider 与后端之间的字段映射（vector_store_id、litellm_credential_name、litellm_params 等）在 types.go 有完整对应关系。

一个值得注意的安全细节

在 resource_vector_store_crud_test.go 中存在一条针对性单测 TestVectorStoreReadDoesNotPersistServerLitellmParams：当 Proxy 响应里带回了 litellm_params（其中可能包含 api_key 这类服务端下发内容）时，资源的 Read 不会把服务端回传的 litellm_params 覆写进 state，从而避免敏感信息泄漏到 Terraform state。这也解释了资源文档中的告诫：不要把 API Key 等密钥放进 litellm_params，应放入独立的 litellm_credential 并通过 litellm_credential_name 引用（参见 vector_store 资源文档）。在使用本数据源的 litellm_params 属性做下游消费时，同样应意识到该 map 可能携带与配置时不同的内容，建议只读取并转发明确非敏感的键。

与资源/凭据/模型的组合编排小结

想要达成的目标	推荐组合
只在 Terraform 中新建向量库	litellm_vector_store 资源 + litellm_credential 资源（密钥管理）
引用外部已存在的向量库	本文主角 litellm_vector_store 数据源
复读向量库所用凭据	数据源输出 litellm_credential_name → litellm_credential 数据源
让模型绑定向量库参与 RAG	数据源/资源输出 vector_store_id → litellm_model 的 additional_litellm_params
把已有向量库纳入 Terraform 管理	terraform import litellm_vector_store.example "vector-store-id"（该资源支持按 ID 导入，见 vector_store 资源文档）

资源与数据源共享同一套 vector_store_id 命名空间与 Proxy 管理端点。若需将某存量向量库从"仅引用"升级为"完全托管"，可在资源文档中使用 terraform import 接管；若仍希望保持"外部负责生命周期、本配置只读消费"，则持续使用数据源即可，两种模式可随时按需切换。

注意事项（Notes）

• 向量存储的 ID 由 LiteLLM 系统统一分配（VectorStoreResponse.VectorStoreID），是全局唯一且稳定的引用键；在 data_source_vector_store.go 中，数据源会把该 ID 同时写回 d.SetId 与 vector_store_id 属性，保证 state 与远端一致。
• 当指定 ID 不存在时，数据源会以 vector store '%s' not found 的形式报错终止，而不是返回空对象——这既是缺陷暴露机制，也是配置自检的利器。
• 全部导出属性均为 Compute-only，反映的是执行 plan/apply 读取时刻的 LiteLLM 真实状态；对象在读取后被外部修改，需在下一次刷新时才会体现。
• 数据源天然适合：跨 Terraform 配置/工作区引用、依赖前置校验、批量状态汇总、审计与合规快照。若目标是由同一份配置完整管理向量库生命周期，则应改用 litellm_vector_store 资源，二者语义需明确区分。
• 请确保你的 LiteLLM Proxy 实例已配置对应供应商的向量库能力且网络可达，否则 Provider 会在 POST /vector_store/info 环节收到非 200 响应并抛出 API request failed 类错误。