grepai-embeddings-openai · Agent Skill

用途

本技能介绍如何在 GrepAI 中使用 OpenAI 的嵌入 API，为代码库生成高质量、基于云端的向量嵌入。

适用场景：

需要最高质量的嵌入
团队环境，使用共享基础设施
不想自行管理本地嵌入服务器
愿意以隐私换取质量与便利

主要能力与考量

质量：使用最先进的嵌入模型
速度：速度快，无需本地计算
可扩展性：可处理任意规模的代码库
隐私：代码会被发送到 OpenAI 服务器
成本：按 token 计费
网络：需要互联网连接

前置条件

OpenAI API 密钥
OpenAI 账户已启用计费
获取 API 密钥地址：https://platform.openai.com/api-keys

配置

基础配置（.grepai/config.yaml）：

embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}

设置环境变量：

export OPENAI_API_KEY="sk-..."

启用并行处理：

embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}
  parallelism: 8  # Concurrent requests for speed

直接写入 API 密钥（不推荐）：

embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: sk-your-api-key-here  # Avoid committing secrets!

警告：切勿将 API 密钥提交到版本控制。

可用模型

text-embedding-3-small（推荐）：

维度：1536
价格：$0.00002 / 1K tokens
质量：非常高
速度：快
最适合：大多数用例，成本与质量平衡良好

embedder:
  provider: openai
  model: text-embedding-3-small

text-embedding-3-large：

维度：3072
价格：$0.00013 / 1K tokens
质量：最高
速度：快
最适合：追求最高准确率、不在意成本

embedder:
  provider: openai
  model: text-embedding-3-large
  dimensions: 3072

维度缩减（可节省存储）：

embedder:
  provider: openai
  model: text-embedding-3-large
  dimensions: 1024  # Reduced from 3072

模型对比：

模型	维度	成本/1K tokens	质量
text-embedding-3-small	1536	$0.00002	⭐⭐⭐⭐
text-embedding-3-large	3072	$0.00013	⭐⭐⭐⭐⭐

成本估算

每 1000 个源文件的近似成本：

代码库规模	分块数	小模型	大模型
小（100 文件）	~500	$0.01	$0.06
中（1000 文件）	~5,000	$0.10	$0.65
大（10000 文件）	~50,000	$1.00	$6.50

注意：成本为初次索引的一次性费用。更新时仅重新嵌入发生变更的文件。

速度优化

并行请求（GrepAI v0.24.0+ 支持自适应限流与并行请求）：

embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}
  parallelism: 8  # Adjust based on your rate limit tier

并行度建议：

Tier 1（免费）：1-2
Tier 2：4-8
Tier 3+：8-16

批处理：GrepAI 会自动对分块进行批处理，以高效使用 API。

速率限制

OpenAI 根据账户层级设有速率限制：

层级	RPM	TPM
Free	3	150,000
Tier 1	500	1,000,000
Tier 2	5,000	5,000,000

GrepAI 通过自适应退避自动处理限流。

环境变量

设置 API 密钥。

macOS/Linux（在 ~/.bashrc、~/.zshrc 或 ~/.profile 中）：

export OPENAI_API_KEY="sk-..."

Windows（PowerShell）：

$env:OPENAI_API_KEY = "sk-..."
# Or permanently
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-...', 'User')

使用 .env 文件：在项目根目录创建 .env：

OPENAI_API_KEY=sk-...

并加入 .gitignore：

.env

Azure OpenAI

用于 Azure 托管的 OpenAI：

embedder:
  provider: openai
  model: your-deployment-name
  api_key: ${AZURE_OPENAI_API_KEY}
  endpoint: https://your-resource.openai.azure.com

安全最佳实践

使用环境变量：切勿硬编码 API 密钥
加入 .gitignore：排除 .env 文件
轮换密钥：定期轮换 API 密钥
监控用量：检查 OpenAI 仪表盘是否有异常用量
审查代码：确保敏感代码未被索引

常见问题

401 Unauthorized：检查 API 密钥是否正确、环境变量是否已设置：echo $OPENAI_API_KEY
429 Rate limit exceeded：降低并行度或升级 OpenAI 层级：

embedder:
  parallelism: 2  # Lower value

成本过高：改用 text-embedding-3-small 而非 large；减小维度；增加忽略规则以减少索引文件
索引缓慢：提高并行度：

embedder:
  parallelism: 8

隐私顾虑：改用 Ollama 进行本地嵌入

从 Ollama 迁移到 OpenAI

更新配置：

embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}

删除现有索引：

rm .grepai/index.gob

重新索引：

grepai watch

重要：不能混用来自不同模型/提供方的嵌入。

输出格式

成功配置 OpenAI 后的输出示例：

✅ OpenAI Embedding Provider Configured

   Provider: OpenAI
   Model: text-embedding-3-small
   Dimensions: 1536
   Parallelism: 4
   API Key: sk-...xxxx (from environment)

   Estimated cost for this codebase:
   - Files: 245
   - Chunks: ~1,200
   - Cost: ~$0.02

   Note: Code will be sent to OpenAI servers.