Weaviate Cloud 免费配额说明：10 万对象与每日 2000 次托管向量化

Weaviate Cloud 不是 OpenAI 式的对话补全接口，它对外提供的是向量数据库的 REST 与 gRPC 接口，外加平台托管的向量化能力和 Query Agent。也就是说，你不需要单独接一条 embedding 管线：把原始文本写进 collection，平台会替你生成向量。

连接地址与认证

REST 基础地址形如 https://你的集群名.weaviate.cloud，gRPC 走同一主机名的 443 端口；完整地址以控制台集群详情页为准。认证统一用集群的 API key，通过 Authorization: Bearer 请求头或客户端 SDK 的认证参数传入。建议先设置环境变量：

export WEAVIATE_URL="https://你的集群名.weaviate.cloud"
export WEAVIATE_API_KEY="你的集群API Key"

建库与写入（Python SDK）

创建 collection 时把向量化器设为平台托管的那一档，模型名在控制台或官方文档里可查，以实际显示为准；不指定时用默认模型即可。下面这段可直接运行：

import os
import weaviate
from weaviate.classes.init import Auth
from weaviate.classes.config import Configure, Property, DataType

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=os.environ["WEAVIATE_URL"],
    auth_credentials=Auth.api_key(os.environ["WEAVIATE_API_KEY"]),
)

if not client.collections.exists("Doc"):
    client.collections.create(
        name="Doc",
        properties=[Property(name="content", data_type=DataType.TEXT)],
        vector_config=Configure.Vectors.text2vec_weaviate(),
    )

col = client.collections.use("Doc")
col.data.insert(properties={"content": "Weaviate 免费档自带托管向量化，可直接写入原始文本。"})

result = col.query.hybrid(query="免费向量库", alpha=0.5, limit=3)
for obj in result.objects:
    print(obj.properties)

client.close()

关键参数说明：name 是 collection 名，重复创建会报错，生产代码里先判断是否存在；vector_config 决定向量由谁生成，选托管档就不要再自己传向量；data.insert 的 properties 里放原始文本，写入时即消耗一次托管向量化配额；alpha 控制混合检索中向量与关键词的权重，取值 0 到 1，0 偏向 BM25 关键词、1 偏向纯向量，做 RAG 原型常用 0.5 到 0.75。

Query Agent 与托管向量化

Query Agent 是按月计量的独立能力，调用入口、请求体字段与端点请以控制台给出的信息和官方文档为准，不要凭猜测拼地址。托管向量化的调用量同样在控制台用量面板查看，脚本里可以先用小批量文本试跑，估算每条记录消耗的次数后再全量导入。

额度耗尽与限流的典型表现

• 写入或查询返回 HTTP 429，错误信息里带 rate limit 或 quota 字样，说明当天向量化次数或请求频率到顶。
• 写入被拒并提示对象数量或磁盘超出上限，说明已经顶到 10 万个对象或 10 GB 磁盘的边界。
• 创建 collection 报错，多半是 Free 档只允许 1 个 collection，先删除旧 collection 或复用它。
• 调用直接 401 或 403，先怀疑 API key 复制不全、带了多余空格，或环境变量没生效。

排查顺序

1. 看控制台用量面板：对象数、磁盘、向量化调用次数、Query Agent 调用次数哪个先到顶。
2. 确认失败请求的 HTTP 状态码与错误文案，429 与 401 的处理方式完全不同。
3. 检查 collection 数量与 tenant 数量是否超限，以及向量化器是否被误设为无。
4. 用小批量单条写入复现，排除批量脚本并发过高导致的频率限制。
5. 以上都正常，再核对集群地址是否带多余路径、gRPC 端口是否被本地网络拦截。

配额到顶后不必删数据，等日配额重置即可继续；但 Free 档的资源上限是硬约束，正式对外服务前应规划好数据规模或评估升级套餐。