133 lines
4.0 KiB
Markdown
133 lines
4.0 KiB
Markdown
# OpenAI Service Setup Guide
|
||
|
||
This document explains how to configure and use the OpenAI service for parsing book metadata from images.
|
||
|
||
## Overview
|
||
|
||
The Bookshelf app now supports two AI services for book cover analysis:
|
||
1. **Google Gemini** (original service)
|
||
2. **OpenAI** (new alternate service)
|
||
|
||
The app will automatically try OpenAI first if configured, and fall back to Gemini if OpenAI fails or is not configured.
|
||
|
||
## Configuration
|
||
|
||
### Step 1: Configure API Keys
|
||
|
||
Edit `lib/config/api_config.dart`:
|
||
|
||
```dart
|
||
class ApiConfig {
|
||
// Gemini API (original service)
|
||
static const String geminiApiKey = 'YOUR_GEMINI_API_KEY_HERE';
|
||
|
||
// OpenAI API (new service)
|
||
static const String openaiApiKey = 'YOUR_OPENAI_API_KEY_HERE';
|
||
|
||
// OpenAI API endpoint
|
||
static const String openaiBaseUrl = 'http://localhost:8317';
|
||
}
|
||
```
|
||
|
||
### Step 2: Replace API Keys
|
||
|
||
Replace the placeholder values with your actual API keys:
|
||
|
||
- **OpenAI API Key**: Get from your OpenAI account or local OpenAI-compatible server
|
||
- **Gemini API Key**: Get from [Google AI Studio](https://makersuite.google.com/app/apikey) (fallback)
|
||
|
||
## OpenAI Service Details
|
||
|
||
### Endpoint Configuration
|
||
|
||
The OpenAI service is configured to use:
|
||
- **Default endpoint**: `http://localhost:8317/v1/chat/completions`
|
||
- **Model**: `glm-4` (vision-capable)
|
||
- **Max tokens**: 500
|
||
- **Temperature**: 0.3
|
||
|
||
**Important**: The server must support the `glm-4` model. This is a required model name for this OpenAI-compatible endpoint.
|
||
|
||
You can customize the endpoint by changing the `openaiBaseUrl` in `api_config.dart`.
|
||
|
||
### How It Works
|
||
|
||
1. The app captures an image using the camera
|
||
2. The image is converted to base64 format
|
||
3. A prompt is sent to the OpenAI API with the image
|
||
4. The API analyzes the image and extracts:
|
||
- Book title
|
||
- Author name
|
||
- Genre (fiction/fantasy/science/detective/biography/other)
|
||
- Brief annotation/description
|
||
5. The parsed data is returned and pre-filled in the add book form
|
||
|
||
### Service Priority
|
||
|
||
The app follows this priority order:
|
||
1. **OpenAI** (if API key is configured) - tried first
|
||
2. **Gemini** (if OpenAI fails or is not configured) - fallback
|
||
|
||
This ensures you always have a working service available.
|
||
|
||
## Testing
|
||
|
||
To test the OpenAI service:
|
||
|
||
1. Make sure your OpenAI server is running at `http://localhost:8317`
|
||
2. Configure your OpenAI API key in `api_config.dart`
|
||
3. Run the app: `flutter run`
|
||
4. Navigate to the "Add Book" screen
|
||
5. Tap the camera icon to scan a book cover
|
||
6. The app will use OpenAI to analyze the image
|
||
|
||
## Troubleshooting
|
||
|
||
### "API ключ не настроен (ни OpenAI, ни Gemini)"
|
||
|
||
This error means neither OpenAI nor Gemini API keys are configured. At least one must be set in `api_config.dart`.
|
||
|
||
### "Не удалось распознать книгу"
|
||
|
||
This can occur if:
|
||
- The API request failed (check your server logs)
|
||
- The image quality is poor
|
||
- The API returned invalid JSON
|
||
- Network connectivity issues
|
||
|
||
### OpenAI Service Not Working
|
||
|
||
If OpenAI fails, the app will automatically fall back to Gemini. Check the console output to see which service is being used:
|
||
|
||
```
|
||
Using OpenAI service for analysis
|
||
```
|
||
or
|
||
```
|
||
Using Gemini service for analysis
|
||
```
|
||
|
||
### Network Issues
|
||
|
||
Make sure:
|
||
- Your OpenAI server is accessible from the device/emulator
|
||
- For Android emulator: Use `10.0.2.2` instead of `localhost`
|
||
- For iOS simulator: `localhost` should work
|
||
- For physical device: Use your machine's actual IP address
|
||
|
||
## Files Modified
|
||
|
||
1. **lib/services/openai_service.dart** - New OpenAI service implementation
|
||
2. **lib/config/api_config.dart** - Added OpenAI configuration
|
||
3. **lib/screens/scanner_screen.dart** - Updated to support both services
|
||
4. **lib/screens/add_book_screen.dart** - Updated to pass OpenAI configuration
|
||
5. **pubspec.yaml** - Added `http` package dependency
|
||
|
||
## Future Enhancements
|
||
|
||
Possible improvements:
|
||
- Add UI option to manually select which service to use
|
||
- Add retry logic with different services
|
||
- Implement caching of recognized books
|
||
- Add support for multiple OpenAI models
|
||
- Add detailed error messages and logging |