246 lines
10 KiB
Plaintext
246 lines
10 KiB
Plaintext
---
|
|
description: Comprehensive best practices and coding standards for projects using the openai library, covering code structure, performance, security, and common pitfalls.
|
|
globs: *.py
|
|
---
|
|
# openai Library Best Practices and Coding Standards
|
|
|
|
This document outlines best practices and coding standards for developing applications using the `openai` library. Following these guidelines will lead to more maintainable, performant, and secure code.
|
|
|
|
## Library Information:
|
|
- Name: openai
|
|
- Tags: ai, ml, llm, api
|
|
|
|
## 1. Code Organization and Structure
|
|
|
|
### 1.1 Directory Structure Best Practices
|
|
|
|
Adopt a clear and consistent directory structure to improve code organization and maintainability. Here's a recommended structure for projects using the openai library:
|
|
|
|
|
|
project_root/
|
|
├── src/ # Source code directory
|
|
│ ├── models/ # Definitions for your models (e.g., data classes, schemas)
|
|
│ ├── services/ # Service layer for interacting with the OpenAI API
|
|
│ │ ├── openai_service.py # Encapsulates OpenAI API calls
|
|
│ ├── utils/ # Utility functions
|
|
│ ├── main.py # Entry point of your application
|
|
├── tests/ # Tests directory
|
|
│ ├── unit/ # Unit tests
|
|
│ ├── integration/ # Integration tests
|
|
│ ├── conftest.py # Pytest configuration file
|
|
├── data/ # Data storage (e.g., prompts, training data)
|
|
├── docs/ # Documentation
|
|
├── .env # Environment variables
|
|
├── requirements.txt # Dependencies
|
|
├── README.md # Project README
|
|
|
|
|
|
### 1.2 File Naming Conventions
|
|
|
|
- Use descriptive and consistent file names.
|
|
- Python files should use snake_case (e.g., `openai_service.py`).
|
|
- Class names should use CamelCase (e.g., `OpenAIService`).
|
|
- Variable names should use snake_case (e.g., `api_key`).
|
|
|
|
### 1.3 Module Organization
|
|
|
|
- Group related functionalities into modules.
|
|
- Avoid circular dependencies between modules.
|
|
- Use clear and concise module names.
|
|
- Use `__init__.py` files to define packages and control namespace.
|
|
|
|
### 1.4 Component Architecture
|
|
|
|
Consider using a layered architecture to separate concerns:
|
|
|
|
- **Presentation Layer:** Handles user interface or external API interactions.
|
|
- **Service Layer:** Encapsulates business logic and interacts with the OpenAI API.
|
|
- **Data Access Layer:** Handles data persistence and retrieval.
|
|
|
|
This separation makes testing and maintenance easier.
|
|
|
|
### 1.5 Code Splitting Strategies
|
|
|
|
- Split large files into smaller, more manageable modules based on functionality.
|
|
- Use abstract base classes and interfaces to define contracts between components.
|
|
- Apply the Single Responsibility Principle (SRP) to classes and functions.
|
|
|
|
## 2. Common Patterns and Anti-patterns
|
|
|
|
### 2.1 Design Patterns
|
|
|
|
- **Factory Pattern:** Use a factory to create OpenAI API client instances with different configurations.
|
|
- **Strategy Pattern:** Implement different prompt strategies based on the task.
|
|
- **Decorator Pattern:** Add logging, caching, or rate limiting to OpenAI API calls.
|
|
|
|
### 2.2 Recommended Approaches
|
|
|
|
- **Prompt Engineering:** Follow best practices for prompt design. Place clear instructions at the beginning of prompts, be specific, and use examples.
|
|
- **Configuration:** Store API keys and other sensitive information in environment variables using a library like `python-dotenv`.
|
|
- **Asynchronous Calls:** Use `asyncio` and `aiohttp` for non-blocking API calls to improve performance.
|
|
- **Retries and Exponential Backoff:** Implement retry mechanisms with exponential backoff to handle transient API errors.
|
|
|
|
### 2.3 Anti-patterns
|
|
|
|
- **Hardcoding API Keys:** Never hardcode API keys directly into your code. Always use environment variables.
|
|
- **Ignoring Rate Limits:** Implement rate limiting to avoid exceeding OpenAI API limits.
|
|
- **Lack of Error Handling:** Always handle API errors gracefully and provide informative error messages.
|
|
- **Overly Complex Prompts:** Keep prompts simple and focused. Break down complex tasks into smaller steps.
|
|
- **Mixing Concerns:** Avoid mixing presentation, business logic, and data access in the same component.
|
|
|
|
### 2.4 State Management
|
|
|
|
- Use appropriate data structures to manage the state of your OpenAI interactions.
|
|
- Consider using a state management library if your application has complex state requirements.
|
|
- Avoid storing sensitive information in application state.
|
|
|
|
### 2.5 Error Handling
|
|
|
|
- Use `try-except` blocks to catch potential exceptions.
|
|
- Log errors with sufficient context for debugging.
|
|
- Implement custom exception classes for specific error conditions.
|
|
- Handle rate limit errors and implement retry logic.
|
|
|
|
## 3. Performance Considerations
|
|
|
|
### 3.1 Optimization Techniques
|
|
|
|
- **Caching:** Cache API responses to reduce the number of API calls.
|
|
- **Batching:** Batch multiple API requests into a single request when possible.
|
|
- **Asynchronous Operations:** Use asynchronous programming to avoid blocking the main thread.
|
|
- **Token Optimization:** Reduce the number of tokens in your prompts to lower costs and improve response times.
|
|
|
|
### 3.2 Memory Management
|
|
|
|
- Be mindful of the size of your prompts and responses, especially when working with large language models.
|
|
- Use generators to process large datasets in chunks.
|
|
- Clean up resources (e.g., file handles, network connections) promptly.
|
|
|
|
### 3.3 Rendering Optimization (If Applicable)
|
|
|
|
- If your application involves rendering OpenAI-generated content, optimize the rendering process to minimize latency.
|
|
|
|
### 3.4 Bundle Size Optimization (If Applicable)
|
|
|
|
- For web applications, minimize bundle size by using tree shaking and code splitting.
|
|
|
|
### 3.5 Lazy Loading
|
|
|
|
- Use lazy loading to load modules or data only when they are needed.
|
|
|
|
## 4. Security Best Practices
|
|
|
|
### 4.1 Common Vulnerabilities
|
|
|
|
- **API Key Exposure:** Protect your OpenAI API key. Never commit it to version control or share it publicly.
|
|
- **Prompt Injection:** Validate and sanitize user inputs to prevent prompt injection attacks.
|
|
- **Data Leakage:** Avoid exposing sensitive data in prompts or API responses.
|
|
|
|
### 4.2 Input Validation
|
|
|
|
- Validate all user inputs to prevent malicious or unexpected data from being sent to the OpenAI API.
|
|
- Sanitize inputs to remove potentially harmful characters or code.
|
|
|
|
### 4.3 Authentication and Authorization
|
|
|
|
- Implement authentication and authorization mechanisms to protect your application and data.
|
|
- Use secure storage for API keys and other sensitive information.
|
|
|
|
### 4.4 Data Protection
|
|
|
|
- Encrypt sensitive data at rest and in transit.
|
|
- Follow data privacy regulations (e.g., GDPR, CCPA).
|
|
|
|
### 4.5 Secure API Communication
|
|
|
|
- Use HTTPS to encrypt communication with the OpenAI API.
|
|
- Verify the authenticity of the OpenAI API server using SSL certificates.
|
|
|
|
## 5. Testing Approaches
|
|
|
|
### 5.1 Unit Testing
|
|
|
|
- Write unit tests for individual components to ensure they function correctly in isolation.
|
|
- Use mocking and stubbing to isolate components from external dependencies (e.g., the OpenAI API).
|
|
|
|
### 5.2 Integration Testing
|
|
|
|
- Write integration tests to verify that different components work together correctly.
|
|
- Test the interaction between your application and the OpenAI API.
|
|
|
|
### 5.3 End-to-End Testing
|
|
|
|
- Write end-to-end tests to simulate user interactions and verify that the entire application works as expected.
|
|
|
|
### 5.4 Test Organization
|
|
|
|
- Organize your tests into a clear and consistent directory structure.
|
|
- Use descriptive test names.
|
|
- Follow a consistent testing style.
|
|
|
|
### 5.5 Mocking and Stubbing
|
|
|
|
- Use mocking libraries like `unittest.mock` or `pytest-mock` to mock the OpenAI API.
|
|
- Create stubs for API responses to control the behavior of the API during testing.
|
|
|
|
## 6. Common Pitfalls and Gotchas
|
|
|
|
### 6.1 Frequent Mistakes
|
|
|
|
- **Not handling API errors:** Implement proper error handling for OpenAI API calls.
|
|
- **Exceeding rate limits:** Implement rate limiting and exponential backoff to avoid exceeding API limits.
|
|
- **Incorrect prompt formatting:** Follow OpenAI's prompt engineering guidelines to optimize model performance.
|
|
- **Not validating inputs:** Validate user inputs to prevent prompt injection attacks and unexpected behavior.
|
|
|
|
### 6.2 Edge Cases
|
|
|
|
- **Handling very long prompts:** Be aware of token limits and consider splitting long prompts into smaller chunks.
|
|
- **Dealing with ambiguous or unclear instructions:** Craft prompts carefully to provide clear and specific instructions.
|
|
- **Handling unexpected API responses:** Implement robust error handling to deal with unexpected API responses.
|
|
|
|
### 6.3 Version-Specific Issues
|
|
|
|
- Be aware of changes between different versions of the `openai` library.
|
|
- Consult the release notes and migration guides when upgrading to a new version.
|
|
|
|
### 6.4 Compatibility Concerns
|
|
|
|
- Ensure compatibility between the `openai` library and other libraries used in your project.
|
|
- Test your application thoroughly after upgrading any dependencies.
|
|
|
|
### 6.5 Debugging Strategies
|
|
|
|
- Use logging to track the flow of your application and identify potential issues.
|
|
- Use a debugger to step through your code and inspect variables.
|
|
- Use unit tests to isolate and debug individual components.
|
|
|
|
## 7. Tooling and Environment
|
|
|
|
### 7.1 Recommended Development Tools
|
|
|
|
- **IDE:** VS Code, PyCharm
|
|
- **Virtual Environment Manager:** venv, conda, pipenv
|
|
- **Package Manager:** pip, poetry
|
|
- **Testing Framework:** pytest, unittest
|
|
- **Linting and Formatting:** pylint, flake8, black
|
|
|
|
### 7.2 Build Configuration
|
|
|
|
- Use a `requirements.txt` or `pyproject.toml` file to manage dependencies.
|
|
- Use a build system like `setuptools` or `poetry` to package your application.
|
|
|
|
### 7.3 Linting and Formatting
|
|
|
|
- Use a linter like `pylint` or `flake8` to enforce coding style guidelines.
|
|
- Use a formatter like `black` to automatically format your code.
|
|
|
|
### 7.4 Deployment Best Practices
|
|
|
|
- Use a containerization technology like Docker to package your application and its dependencies.
|
|
- Deploy your application to a cloud platform like AWS, Azure, or Google Cloud.
|
|
- Use a process manager like `systemd` or `supervisor` to manage your application.
|
|
|
|
### 7.5 CI/CD Integration
|
|
|
|
- Use a CI/CD pipeline to automate the build, test, and deployment process.
|
|
- Integrate your tests into the CI/CD pipeline to ensure that all changes are thoroughly tested before being deployed. |