grepai-embeddings-openai

使用 OpenAI 的 GrepAI 嵌入

本技能介绍如何将 OpenAI 的嵌入 API 与 GrepAI 搭配使用，以获得高质量的云端嵌入。

何时使用此技能

• 需要最高质量的嵌入
• 团队环境中使用共享基础设施
• 不想管理本地嵌入服务
• 愿意以牺牲隐私换取质量和便利性

注意事项

方面	详情
✅ 质量	最先进的嵌入
✅ 速度	速度快，无需本地计算
✅ 可扩展性	可处理任意规模的代码库
⚠️ 隐私	代码会发送到 OpenAI 服务
⚠️ 费用	按 Token 付费
⚠️ 互联网	需要网络连接

前提条件

1. OpenAI API 密钥
2. 已在 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 Token
质量	非常高
速度	快

**适用场景：**大多数用例，在成本和质量之间实现良好平衡。

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

text-embedding-3-large

属性	值
维度	3072
价格	$0.00013 / 1K Token
质量	最高
速度	快

**适用场景：**追求最高准确度，且不考虑成本。

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

降低维度

你可以降低维度以节省存储空间：

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

模型比较

模型	维度	每 1K Token 的成本	质量
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
免费	3	150,000
Tier 1	500	1,000,000
Tier 2	5,000	5,000,000

GrepAI 会通过自适应退避自动处理速率限制。

环境变量

设置 API 密钥

macOS/Linux：

# In ~/.bashrc, ~/.zshrc, or ~/.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

安全最佳实践

1. **使用环境变量：**切勿将 API 密钥硬编码
2. **添加到 .gitignore：**排除 .env 文件
3. **轮换密钥：**定期轮换 API 密钥
4. **监控用量：**在 OpenAI 控制面板中检查是否存在异常用量
5. **审查代码：**确保不会索引敏感代码

常见问题

❌ 问题： 401 Unauthorized ✅ **解决方案：**检查 API 密钥是否正确，以及是否已设置环境变量：

echo $OPENAI_API_KEY

❌ 问题： 429 Rate limit exceeded ✅ **解决方案：**降低并行度，或升级 OpenAI 层级：

embedder:
  parallelism: 2  # Lower value

❌ **问题：**成本过高 ✅ 解决方案：

• 使用 text-embedding-3-small 代替大型模型
• 降低维度
• 添加更多忽略规则，以减少索引文件

❌ **问题：**索引速度慢 ✅ **解决方案：**提高并行度：

embedder:
  parallelism: 8

❌ **问题：**隐私顾虑 ✅ **解决方案：**改用 Ollama 进行本地嵌入

从 Ollama 迁移到 OpenAI

1. 更新配置：

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

2. 删除现有索引：

rm .grepai/index.gob

3. 重新建立索引：

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.