API_SETUP.md

API 配置指南

为什么需要配置 API？

Hugging Face 的免费 Inference API 有速率限制，某些模型可能需要认证 token 才能使用。配置 token 可以提高：

• API 调用成功率
• 响应速度
• 可用模型范围

方法1: 添加 Hugging Face Access Token（推荐）

步骤1: 创建 Access Token

1. 访问：https://huggingface.co/settings/tokens
2. 点击 "New token"
3. 填写信息：
   • Name: space-api-token（或任意名称）
   • Type: 选择 Write（需要写入权限才能使用某些模型）
4. 点击 "Generate a token"
5. 重要：复制生成的 token（只显示一次！）

步骤2: 在 Space 中添加 Token

1. 进入你的 Space 页面
2. 点击 "Settings"（设置）
3. 找到 "Variables and secrets" 部分
4. 点击 "New secret"
5. 添加：
   • Key: HF_API_TOKEN
   • Value: 粘贴你刚才复制的 token
6. 点击 "Add secret"
7. Space 会自动重新构建

步骤3: 测试

等待 Space 重新构建完成后，测试聊天功能。如果配置正确，API 调用应该会成功。

方法2: 使用其他模型

如果默认模型不可用，可以在 Space 设置中指定其他模型：

在 Space 设置中添加环境变量

1. 进入 Space Settings
2. 找到 "Variables and secrets"
3. 添加新的环境变量：
   • Key: HF_API_URL
   • Value: 选择以下之一：
     • https://api-inference.huggingface.co/models/elyza/ELYZA-japanese-Llama-2-7b-instruct
     • https://api-inference.huggingface.co/models/cyberagent/calm2-7b-chat
     • https://api-inference.huggingface.co/models/mistralai/Mistral-7B-Instruct-v0.2

方法3: 使用 OpenAI API（可选）

如果你有 OpenAI API key，也可以使用 OpenAI 的模型。需要修改代码，我可以帮你实现。

当前代码的自动重试机制

代码已经实现了自动重试多个模型的功能：

1. 主模型: elyza/ELYZA-japanese-Llama-2-7b-fast-instruct
2. 备用模型1: elyza/ELYZA-japanese-Llama-2-7b-instruct
3. 备用模型2: cyberagent/calm2-7b-chat
4. 备用模型3: mistralai/Mistral-7B-Instruct-v0.2

如果主模型失败，会自动尝试备用模型。

检查 API 状态

查看 Logs

在 Space 的 "Logs" 标签中，你可以看到：

• 哪些模型被尝试了
• 每个模型的响应状态码
• 错误信息（如果有）

常见状态码

• 200: 成功 ✅
• 503: 模型正在加载中，需要等待
• 410: 模型端点不可用（已移除）
• 404: 模型不存在
• 401: 需要认证 token
• 429: 速率限制（请求太频繁）

故障排除

问题1: 所有模型都返回 410 或 404

解决方案:

• 检查模型名称是否正确
• 尝试使用其他模型
• 添加 HF_API_TOKEN 可能有助于访问某些模型

问题2: 返回 503（模型加载中）

解决方案:

• 这是正常的，模型需要时间加载
• 等待提示的时间后重试
• 或者代码会自动尝试下一个模型

问题3: 返回 401（需要认证）

解决方案:

• 添加 HF_API_TOKEN 环境变量
• 确保 token 有正确的权限

问题4: 返回 429（速率限制）

解决方案:

• 等待一段时间后重试
• 添加 HF_API_TOKEN 可以提高速率限制
• 考虑使用付费 API 计划

测试 API 是否工作

你可以手动测试 API：

curl https://api-inference.huggingface.co/models/elyza/ELYZA-japanese-Llama-2-7b-fast-instruct \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "こんにちは"}'

推荐配置

为了获得最佳体验，建议：

1. ✅ 添加 HF_API_TOKEN（提高成功率和速率限制）
2. ✅ 使用默认的主模型（已经过优化）
3. ✅ 让代码自动尝试备用模型（已实现）

需要帮助？

如果遇到问题：

1. 查看 Space 的 Logs 标签
2. 检查环境变量是否正确设置
3. 确认 token 是否有效
4. 尝试不同的模型