docs(README): 添加 API 连接问题常见问答

linzehao · linzehao · commit 1b069801068c · 2025-03-30T12:11:38.000+08:00
- 新增 FAQ 部分解答 API连接相关问题
- 解释跨域问题 (CORS) 是导致连接失败的主要原因
- 提供 Ollama 连接问题的解决方案
- 介绍使用Vercel 代理和自部署 API 中转服务的方法
- 提醒使用 Vercel 代理可能触发的风险控制问题
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # Prompt Optimizer (提示词优化器) 🚀
 
+[English](README_EN.md) | [中文](README.md)
+
 <div align="center">
 
 [![GitHub stars](https://img.shields.io/github/stars/linshenkx/prompt-optimizer)](https://github.com/linshenkx/prompt-optimizer/stargazers)
@@ -12,8 +14,6 @@
 
 [在线体验](https://prompt.always200.com) | [安装指南](#快速开始) | [开发文档](dev.md) | [Chrome插件](https://chromewebstore.google.com/detail/prompt-optimizer/cakkkhboolfnadechdlgdcnjammejlna)
 
-[English](README_EN.md) | [中文](README.md)
-
 </div>
 
 ## 📖 项目简介
@@ -125,6 +125,7 @@ pnpm dev:fresh        # 完整重置并重新启动开发环境
 - [项目状态](docs/project-status.md) - 当前进度和计划
 - [产品需求](docs/prd.md) - 产品需求文档
 
+
 ## Star History
 
 <a href="https://star-history.com/#linshenkx/prompt-optimizer&Date">
@@ -135,6 +136,36 @@ pnpm dev:fresh        # 完整重置并重新启动开发环境
  </picture>
 </a>
 
+## ❓ 常见问题解答（FAQ）
+
+### API连接问题
+
+#### Q1: 为什么配置好API密钥后仍然无法连接到模型服务？
+**A**: 大多数连接失败是由**跨域问题**（CORS）导致的。由于本项目是纯前端应用，浏览器出于安全考虑会阻止直接访问不同源的API服务。模型服务如未正确配置CORS策略，会拒绝来自浏览器的直接请求。
+
+#### Q2: 如何解决本地Ollama的连接问题？
+**A**: Ollama完全支持OpenAI标准接口，只需配置正确的跨域策略：
+1. 设置环境变量 `OLLAMA_ORIGINS=*` 允许任意来源的请求
+2. 如仍有问题，设置 `OLLAMA_HOST=0.0.0.0:11434` 监听任意IP地址
+
+#### Q3: 如何解决商业API（如Nvidia的DS API、字节跳动的火山API）的跨域问题？
+**A**: 这些平台通常有严格的跨域限制，推荐以下解决方案：
+
+1. **使用Vercel代理**（便捷方案）
+   - 使用在线版本：[prompt.always200.com](https://prompt.always200.com)
+   - 或自行部署到Vercel平台
+   - 在模型设置中勾选"使用Vercel代理"选项
+   - 请求流向：浏览器→Vercel→模型服务提供商
+
+2. **使用自部署的API中转服务**（可靠方案）
+   - 部署如OneAPI等开源API聚合/代理工具
+   - 在设置中配置为自定义API端点
+   - 请求流向：浏览器→中转服务→模型服务提供商
+
+#### Q4: Vercel代理有什么缺点或风险？
+**A**: 使用Vercel代理可能会触发某些模型服务提供商的风控机制。部分厂商可能会将来自Vercel的请求判定为代理行为，从而限制或拒绝服务。如遇此问题，建议使用自部署的中转服务。
+
+
 ## 🤝 参与贡献
 
 1. Fork 本仓库
diff --git a/README_EN.md b/README_EN.md
@@ -1,5 +1,7 @@
 # Prompt Optimizer 🚀
 
+[English](README_EN.md) | [中文](README.md)
+
 <div align="center">
 
 [![GitHub stars](https://img.shields.io/github/stars/linshenkx/prompt-optimizer)](https://github.com/linshenkx/prompt-optimizer/stargazers)
@@ -12,8 +14,6 @@
 
 [Live Demo](https://prompt.always200.com) | [Installation](#quick-start) | [Development Docs](dev.md) | [Chrome Extension](https://chromewebstore.google.com/detail/prompt-optimizer/cakkkhboolfnadechdlgdcnjammejlna)
 
-[English](README_EN.md) | [中文](README.md)
-
 </div>
 
 ## 📖 Project Introduction
@@ -135,6 +135,35 @@ For detailed project status, see [Project Status Document](docs/project-status.m
  </picture>
 </a>
 
+## ❓ Frequently Asked Questions (FAQ)
+
+### API Connection Issues
+
+#### Q1: Why can't I connect to the model service after configuring the API key?
+**A**: Most connection failures are caused by **Cross-Origin Resource Sharing (CORS)** issues. As this project is a pure frontend application, browsers block direct access to API services from different origins for security reasons. Model services will reject direct requests from browsers if CORS policies are not correctly configured.
+
+#### Q2: How to solve Ollama connection issues?
+**A**: Ollama fully supports the OpenAI standard interface, just configure the correct CORS policy:
+1. Set environment variable `OLLAMA_ORIGINS=*` to allow requests from any origin
+2. If issues persist, set `OLLAMA_HOST=0.0.0.0:11434` to listen on any IP address
+
+#### Q3: How to solve CORS issues with commercial APIs (such as Nvidia's DS API, ByteDance's Volcano API)?
+**A**: These platforms typically have strict CORS restrictions. Recommended solutions:
+
+1. **Use Vercel Proxy** (Convenient solution)
+   - Use the online version: [prompt.always200.com](https://prompt.always200.com)
+   - Or deploy to your own Vercel platform
+   - Check "Use Vercel Proxy" option in model settings
+   - Request flow: Browser → Vercel → Model service provider
+
+2. **Use self-deployed API proxy service** (Reliable solution)
+   - Deploy open-source API aggregation/proxy tools like OneAPI
+   - Configure as custom API endpoint in settings
+   - Request flow: Browser → Proxy service → Model service provider
+
+#### Q4: What are the drawbacks or risks of using Vercel proxy?
+**A**: Using Vercel proxy may trigger risk control mechanisms of some model service providers. Some vendors may identify requests from Vercel as proxy behavior, thereby limiting or denying service. If you encounter this issue, we recommend using a self-deployed proxy service.
+
 ## 🤝 Contributing
 
 1. Fork the repository
diff --git a/packages/ui/src/components/ModelManager.vue b/packages/ui/src/components/ModelManager.vue
@@ -164,6 +164,7 @@
                     />
                     <label :for="`vercel-proxy-${editingModel.key}`" class="text-sm font-medium theme-manager-text">
                       {{ t('modelManager.useVercelProxy') }}
+                      <span class="cursor-help ml-1" :title="t('modelManager.useVercelProxyHint')">?</span>
                     </label>
                   </div>
                   <div class="flex justify-end space-x-3 pt-4">
@@ -245,7 +246,8 @@
                       class="w-4 h-4 text-purple-600 bg-black/20 border-purple-600/50 rounded focus:ring-purple-500/50"
                     />
                     <label for="new-model-vercel-proxy" class="text-sm font-medium theme-manager-text">
-                      {{ t('modelManager.useVercelProxyHint') }}
+                      {{ t('modelManager.useVercelProxy') }}
+                      <span class="cursor-help ml-1" :title="t('modelManager.useVercelProxyHint')">?</span>
                     </label>
                   </div>
                   <div class="flex justify-end space-x-3 pt-4">
diff --git a/packages/ui/src/i18n/locales/en-US.ts b/packages/ui/src/i18n/locales/en-US.ts
@@ -79,7 +79,7 @@ export default {
     clickToFetchModels: 'Click arrow to fetch model list',
     apiKey: 'API Key',
     useVercelProxy: 'Use Vercel Proxy',
-    useVercelProxyHint: 'Using Vercel proxy can help resolve connection issues in certain regions',
+    useVercelProxyHint: 'Using Vercel proxy can solve CORS issues, but may trigger risk control from some providers. Please use with caution',
     addModel: 'Add',
 
     // Placeholders
diff --git a/packages/ui/src/i18n/locales/zh-CN.ts b/packages/ui/src/i18n/locales/zh-CN.ts
@@ -79,7 +79,7 @@ export default {
     clickToFetchModels: '点击箭头获取模型列表',
     apiKey: 'API密钥',
     useVercelProxy: '使用Vercel代理',
-    useVercelProxyHint: '使用Vercel代理可以帮助解决某些地区的连接问题',
+    useVercelProxyHint: '使用Vercel代理可以解决跨域问题，但可能触发部分厂商风控，请酌情使用',
     addModel: '添加',
 
     // 占位符
