Refactor Agent API to Chat API for AI interactions
- Replaced the Agent API with the Chat API, focusing on AI chat completions with full OpenAI client compatibility and real-time streaming capabilities. - Updated routing to attach chat handlers instead of agent handlers, ensuring OAuth protection for all endpoints. - Revised README documentation to reflect the new Chat API structure, including detailed descriptions of endpoints, features, and usage examples. - Removed the deprecated agent files and their associated documentation to streamline the codebase.
This commit is contained in:
Max
parent
f54d030486
commit
1f2eaf6974
5 changed files with 628 additions and 373 deletions
|
|
@ -271,37 +271,56 @@ The DSL Management API provides:
|
|||
|
||||
All DSL endpoints require OAuth authentication.
|
||||
|
||||
## Agent API
|
||||
## Chat API
|
||||
|
||||
Comprehensive API for AI agent interactions and chat completions with real-time streaming capabilities.
|
||||
Comprehensive API for AI chat completions with **100% OpenAI client compatibility** and real-time streaming capabilities.
|
||||
|
||||
**[View Full Agent API Documentation →](agent/README.md)**
|
||||
**[View Full Chat API Documentation →](chat/README.md)**
|
||||
|
||||
The Agent API provides:
|
||||
The Chat API provides:
|
||||
|
||||
- **OpenAI Client Compatibility**: 100% compatible with existing OpenAI client libraries and SDKs
|
||||
- **Chat Completions**: AI-powered chat with streaming responses via Server-Sent Events
|
||||
- **Assistant Selection**: Multiple AI assistants with different capabilities and personalities
|
||||
- **Standard Compliance**: Full OpenAI API specification compliance
|
||||
- **Context Management**: Persistent chat sessions with conversation history
|
||||
- **Real-Time Streaming**: Server-Sent Events for immediate response delivery
|
||||
- **Session Management**: Automatic session handling with user identification
|
||||
- **Flexible Parameters**: Configurable behavior for different client types and use cases
|
||||
- **Dual Format Support**: Both OpenAI standard and Yao simplified parameter formats
|
||||
|
||||
**Key Endpoints:**
|
||||
|
||||
- `GET /agent/chat/completions` - Stream chat completions with query parameters
|
||||
- `POST /agent/chat/completions` - Stream chat completions with form data
|
||||
- `GET /chat/completions` - Stream chat completions with query parameters (Yao format)
|
||||
- `POST /chat/completions` - Stream chat completions with JSON body (OpenAI format)
|
||||
|
||||
**Features:**
|
||||
**OpenAI Compatibility Features:**
|
||||
|
||||
- **Server-Sent Events**: Real-time streaming responses reduce latency
|
||||
- **Multi-Assistant Support**: Choose from different AI assistants (`mohe`, `developer`, `analyst`, etc.)
|
||||
- **Context Awareness**: Conversation history and additional context support
|
||||
- **Silent Mode**: Configurable verbose/quiet response modes
|
||||
- **Client Customization**: Client-type specific behavior and formatting
|
||||
- **Zero Code Migration**: Existing OpenAI code works with just URL/token changes
|
||||
- **Client Library Support**: Works with OpenAI Python, Node.js, Go, and other clients
|
||||
- **Standard Response Format**: OpenAI-compatible streaming response structure
|
||||
- **Parameter Compatibility**: Supports `model`, `messages`, `temperature`, `max_tokens`, etc.
|
||||
- **Error Format**: OpenAI-compatible error response structure
|
||||
|
||||
**Note:** This is a temporary implementation for full-process testing, and the interface may undergo significant global changes in the future.
|
||||
**Yao Extensions:**
|
||||
|
||||
All Agent endpoints require OAuth authentication.
|
||||
- **Simplified Input**: Use `content` parameter for basic interactions
|
||||
- **Assistant Selection**: Choose from Yao assistants (`mohe`, `developer`, `analyst`, etc.)
|
||||
- **Context Awareness**: Additional context and conversation history support
|
||||
- **Session Management**: Automatic session handling with user identification
|
||||
|
||||
**Migration Example:**
|
||||
|
||||
```python
|
||||
# Before (OpenAI)
|
||||
openai.api_key = "sk-..."
|
||||
|
||||
# After (Yao - Only 2 lines change!)
|
||||
openai.api_base = "https://your-yao.com/v1"
|
||||
openai.api_key = "your-oauth-token"
|
||||
```
|
||||
|
||||
**Note:** This is a temporary implementation for full-process testing, and the interface may undergo significant global changes in the future. However, OpenAI compatibility will be maintained.
|
||||
|
||||
All Chat endpoints require OAuth authentication.
|
||||
|
||||
## File Management API
|
||||
|
||||
|
|
@ -452,32 +471,52 @@ curl -X POST "/v1/dsl/create/model" \
|
|||
}'
|
||||
```
|
||||
|
||||
### AI Agent Chat Interaction
|
||||
### AI Chat Interaction (OpenAI Compatible)
|
||||
|
||||
1. **Start a chat conversation**:
|
||||
1. **Start a chat conversation (OpenAI format)**:
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/agent/chat/completions?content=What%20is%20Yao%20framework?" \
|
||||
curl -X POST "/v1/chat/completions" \
|
||||
-H "Authorization: Bearer {access_token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "mohe",
|
||||
"messages": [
|
||||
{"role": "user", "content": "What is Yao framework?"}
|
||||
],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
2. **Continue conversation with context**:
|
||||
2. **Continue conversation with OpenAI client (Python)**:
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/agent/chat/completions?content=Show%20me%20an%20example&chat_id=chat_123&assistant_id=developer" \
|
||||
-H "Authorization: Bearer {access_token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```python
|
||||
import openai
|
||||
|
||||
# Configure for Yao (only 2 lines change from OpenAI!)
|
||||
openai.api_base = "https://your-yao.com/v1"
|
||||
openai.api_key = "your-oauth-token"
|
||||
|
||||
# Use exactly like OpenAI
|
||||
response = openai.ChatCompletion.create(
|
||||
model="developer",
|
||||
messages=[
|
||||
{"role": "user", "content": "Show me an example"}
|
||||
],
|
||||
stream=True
|
||||
)
|
||||
|
||||
for chunk in response:
|
||||
if chunk.choices[0].delta.get("content"):
|
||||
print(chunk.choices[0].delta.content, end="")
|
||||
```
|
||||
|
||||
3. **Use POST with form data**:
|
||||
3. **Use Yao simplified format**:
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/agent/chat/completions" \
|
||||
curl -X GET "/v1/chat/completions?content=Help%20me%20create%20a%20user%20model&assistant_id=developer" \
|
||||
-H "Authorization: Bearer {access_token}" \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-H "Accept: text/event-stream" \
|
||||
-d "content=Help me create a user model&silent=true&client_type=api"
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
### File Upload and Management
|
||||
|
|
|
|||
|
|
@ -1,337 +0,0 @@
|
|||
# Agent API
|
||||
|
||||
This document describes the RESTful API for AI agent interactions and chat completions in Yao applications.
|
||||
|
||||
## Base URL
|
||||
|
||||
All endpoints are prefixed with the configured base URL followed by `/agent` (e.g., `/v1/agent`).
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require OAuth authentication via the configured OAuth provider.
|
||||
|
||||
## Overview
|
||||
|
||||
The Agent API provides AI-powered chat completion capabilities with support for:
|
||||
|
||||
- **Server-Sent Events (SSE)** - Real-time streaming responses
|
||||
- **Context Management** - Persistent chat sessions with history
|
||||
- **Assistant Selection** - Multiple AI assistants with different capabilities
|
||||
- **Flexible Parameters** - Configurable behavior for different use cases
|
||||
- **Session Management** - Automatic session handling with user identification
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Chat Completions
|
||||
|
||||
Create AI chat completions with streaming responses using Server-Sent Events.
|
||||
|
||||
```
|
||||
GET /chat/completions?content={content}&chat_id={chat_id}&assistant_id={assistant_id}&context={context}&silent={silent}&history_visible={history_visible}&client_type={client_type}
|
||||
POST /chat/completions
|
||||
```
|
||||
|
||||
**Note:** This is a temporary implementation for full-process testing, and the interface may undergo significant global changes in the future.
|
||||
|
||||
**Query Parameters (GET) / Form Data (POST):**
|
||||
|
||||
- `content` (required): The user's message or question
|
||||
- `chat_id` (optional): Chat session identifier (auto-generated if not provided)
|
||||
- `assistant_id` (optional): Specific assistant to use (defaults to system default)
|
||||
- `context` (optional): Additional context for the conversation
|
||||
- `silent` (optional): Silent mode flag ("true"/"false" or "1"/"0")
|
||||
- `history_visible` (optional): Whether chat history is visible ("true"/"false" or "1"/"0")
|
||||
- `client_type` (optional): Client type identifier for customization
|
||||
|
||||
**Headers:**
|
||||
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
**Response Headers:**
|
||||
|
||||
```
|
||||
Content-Type: text/event-stream;charset=utf-8
|
||||
Cache-Control: no-cache
|
||||
Connection: keep-alive
|
||||
```
|
||||
|
||||
**Example GET Request:**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/agent/chat/completions?content=Hello%2C%20how%20are%20you%3F&chat_id=chat_123&assistant_id=mohe" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
**Example POST Request:**
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/agent/chat/completions" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-H "Accept: text/event-stream" \
|
||||
-d "content=Hello, how are you?&chat_id=chat_123&assistant_id=mohe"
|
||||
```
|
||||
|
||||
**Response (Server-Sent Events):**
|
||||
|
||||
The response is streamed as Server-Sent Events with the following format:
|
||||
|
||||
```
|
||||
data: {"type":"message","content":"Hello! I'm doing well, thank you for asking.","role":"assistant","timestamp":1640995200}
|
||||
|
||||
data: {"type":"done","chat_id":"chat_123","session_id":"session_456"}
|
||||
```
|
||||
|
||||
**Response Data Types:**
|
||||
|
||||
- `message` - Content chunk from the AI assistant
|
||||
- `error` - Error message if something goes wrong
|
||||
- `done` - Indicates completion of the response
|
||||
|
||||
**Success Response Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "message",
|
||||
"content": "Hello! I'm an AI assistant created by Yao. How can I help you today?",
|
||||
"role": "assistant",
|
||||
"chat_id": "chat_123",
|
||||
"timestamp": 1640995200
|
||||
}
|
||||
```
|
||||
|
||||
**Completion Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "done",
|
||||
"chat_id": "chat_123",
|
||||
"session_id": "session_456"
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters in Detail
|
||||
|
||||
### Content Parameter
|
||||
|
||||
The `content` parameter is the main user input:
|
||||
|
||||
- **Required** for all requests
|
||||
- Can be a question, command, or conversation message
|
||||
- Supports natural language input
|
||||
- Maximum length depends on assistant configuration
|
||||
|
||||
### Chat ID Management
|
||||
|
||||
The `chat_id` parameter manages conversation continuity:
|
||||
|
||||
- **Auto-generated** if not provided (format: `chat_{timestamp}`)
|
||||
- **Persistent** across multiple requests for the same conversation
|
||||
- **Unique** identifier for each chat session
|
||||
- Used for conversation history and context management
|
||||
|
||||
### Assistant Selection
|
||||
|
||||
The `assistant_id` parameter allows choosing specific AI assistants:
|
||||
|
||||
- **Optional** - defaults to system default assistant
|
||||
- **Different assistants** may have different capabilities, knowledge bases, or personalities
|
||||
- **Examples**: `mohe`, `developer`, `analyst`
|
||||
|
||||
### Context and Behavior
|
||||
|
||||
Additional parameters for fine-tuning behavior:
|
||||
|
||||
- `context` - Provides additional context for better responses
|
||||
- `silent` - Controls verbose/quiet response modes
|
||||
- `history_visible` - Controls whether conversation history affects responses
|
||||
- `client_type` - Allows client-specific customizations
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return standardized error responses via Server-Sent Events:
|
||||
|
||||
```
|
||||
data: {"type":"error","error":"invalid_request","error_description":"content is required"}
|
||||
```
|
||||
|
||||
**Common Error Types:**
|
||||
|
||||
- `invalid_request` - Missing required parameters
|
||||
- `unauthorized` - Authentication failure
|
||||
- `assistant_not_found` - Invalid assistant ID
|
||||
- `internal_error` - Server processing error
|
||||
|
||||
**HTTP Status Codes:**
|
||||
|
||||
- `200` - Success (streaming response)
|
||||
- `400` - Bad Request (missing content parameter)
|
||||
- `401` - Unauthorized (authentication required)
|
||||
- `500` - Internal Server Error
|
||||
|
||||
## Session Management
|
||||
|
||||
The Agent API automatically manages sessions:
|
||||
|
||||
### Session Creation
|
||||
|
||||
- **Automatic** session creation when `__sid` is not present
|
||||
- **UUID generation** for new sessions
|
||||
- **Session persistence** across requests
|
||||
|
||||
### Session Context
|
||||
|
||||
- **User identification** through session data
|
||||
- **Conversation history** maintained per chat_id
|
||||
- **Context preservation** between messages
|
||||
|
||||
## Real-Time Streaming
|
||||
|
||||
The API uses Server-Sent Events for real-time communication:
|
||||
|
||||
### Connection Management
|
||||
|
||||
- **Keep-alive** connections for streaming
|
||||
- **Automatic reconnection** support
|
||||
- **Graceful error handling**
|
||||
|
||||
### Event Types
|
||||
|
||||
- **message** - Streaming content chunks
|
||||
- **error** - Error notifications
|
||||
- **done** - Completion indicators
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Simple Chat Interaction
|
||||
|
||||
1. **Start a conversation:**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/agent/chat/completions?content=What%20is%20Yao?" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
2. **Continue the conversation:**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/agent/chat/completions?content=Tell%20me%20more%20about%20its%20features&chat_id=chat_123" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
### Assistant-Specific Interaction
|
||||
|
||||
1. **Use a specific assistant:**
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/agent/chat/completions" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-H "Accept: text/event-stream" \
|
||||
-d "content=Help me debug this code&assistant_id=developer&chat_id=debug_session_456"
|
||||
```
|
||||
|
||||
### Context-Aware Conversation
|
||||
|
||||
1. **Provide additional context:**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/agent/chat/completions?content=Optimize%20this%20query&context=PostgreSQL%20database%20with%20large%20user%20table&assistant_id=analyst" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
### Silent Mode Operation
|
||||
|
||||
1. **Use silent mode for concise responses:**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/agent/chat/completions?content=Generate%20user%20model&silent=true&client_type=api" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
## JavaScript Client Example
|
||||
|
||||
Here's how to consume the streaming API in JavaScript:
|
||||
|
||||
```javascript
|
||||
const eventSource = new EventSource(
|
||||
"/v1/agent/chat/completions?content=Hello&chat_id=chat_123",
|
||||
{
|
||||
headers: {
|
||||
Authorization: "Bearer " + accessToken,
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
eventSource.onmessage = function (event) {
|
||||
const data = JSON.parse(event.data);
|
||||
|
||||
switch (data.type) {
|
||||
case "message":
|
||||
console.log("Assistant:", data.content);
|
||||
break;
|
||||
case "error":
|
||||
console.error("Error:", data.error_description);
|
||||
break;
|
||||
case "done":
|
||||
console.log("Conversation completed");
|
||||
eventSource.close();
|
||||
break;
|
||||
}
|
||||
};
|
||||
|
||||
eventSource.onerror = function (error) {
|
||||
console.error("Connection error:", error);
|
||||
};
|
||||
```
|
||||
|
||||
## Integration Considerations
|
||||
|
||||
### Performance
|
||||
|
||||
- **Streaming responses** reduce perceived latency
|
||||
- **Connection pooling** for multiple concurrent chats
|
||||
- **Automatic session cleanup** prevents memory leaks
|
||||
|
||||
### Security
|
||||
|
||||
- **OAuth 2.1 authentication** required for all requests
|
||||
- **Session-based access control**
|
||||
- **Input validation** and sanitization
|
||||
- **Rate limiting** (configured at server level)
|
||||
|
||||
### Scalability
|
||||
|
||||
- **Stateless design** (session data in external store)
|
||||
- **Load balancer compatible** (sticky sessions not required)
|
||||
- **Horizontal scaling** support
|
||||
|
||||
## Development Notes
|
||||
|
||||
**Important:** This is a temporary implementation for full-process testing. The interface design and functionality may undergo significant global changes in future versions. Consider this API experimental and subject to breaking changes.
|
||||
|
||||
### Current Limitations
|
||||
|
||||
- Limited error recovery mechanisms
|
||||
- Basic assistant selection logic
|
||||
- Simplified context management
|
||||
- Minimal response formatting options
|
||||
|
||||
### Future Enhancements
|
||||
|
||||
Future versions may include:
|
||||
|
||||
- Enhanced context management
|
||||
- Advanced assistant capabilities
|
||||
- Improved error handling
|
||||
- Extended parameter options
|
||||
- WebSocket support as alternative to SSE
|
||||
|
||||
This Agent API provides a foundation for AI-powered interactions in Yao applications with real-time streaming capabilities and flexible configuration options.
|
||||
553
openapi/chat/README.md
Normal file
553
openapi/chat/README.md
Normal file
|
|
@ -0,0 +1,553 @@
|
|||
# Chat API
|
||||
|
||||
This document describes the RESTful API for AI chat completions in Yao applications, providing **100% compatibility with OpenAI clients**.
|
||||
|
||||
## Base URL
|
||||
|
||||
All endpoints are prefixed with the configured base URL followed by `/chat` (e.g., `/v1/chat`).
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require OAuth authentication via the configured OAuth provider.
|
||||
|
||||
## Overview
|
||||
|
||||
The Chat API provides AI-powered chat completion capabilities with **full OpenAI API compatibility**, supporting:
|
||||
|
||||
- **OpenAI Client Compatibility** - 100% compatible with existing OpenAI client libraries
|
||||
- **Server-Sent Events (SSE)** - Real-time streaming responses
|
||||
- **Context Management** - Persistent chat sessions with history
|
||||
- **Assistant Selection** - Multiple AI assistants with different capabilities
|
||||
- **Flexible Parameters** - Standard OpenAI parameters plus Yao-specific extensions
|
||||
- **Session Management** - Automatic session handling with user identification
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Chat Completions
|
||||
|
||||
Create AI chat completions with streaming responses using Server-Sent Events. This endpoint is **100% compatible with OpenAI's `/v1/chat/completions` API**.
|
||||
|
||||
```
|
||||
GET /completions?content={content}&chat_id={chat_id}&assistant_id={assistant_id}&context={context}&silent={silent}&history_visible={history_visible}&client_type={client_type}
|
||||
POST /completions
|
||||
```
|
||||
|
||||
**Note:** This is a temporary implementation for full-process testing, and the interface may undergo significant global changes in the future.
|
||||
|
||||
**OpenAI Compatibility:**
|
||||
|
||||
- **Endpoint Path**: `/chat/completions` (matches OpenAI exactly)
|
||||
- **Request Format**: Supports both OpenAI standard and Yao-extended parameters
|
||||
- **Response Format**: Compatible with OpenAI response structure
|
||||
- **Client Libraries**: Works with existing OpenAI SDKs and client libraries
|
||||
|
||||
**Query Parameters (GET) / Form Data (POST):**
|
||||
|
||||
**Standard OpenAI Parameters:**
|
||||
|
||||
- `model` (optional): AI model to use (mapped to `assistant_id` internally)
|
||||
- `messages` (optional): Array of message objects (OpenAI format)
|
||||
- `temperature` (optional): Sampling temperature
|
||||
- `max_tokens` (optional): Maximum tokens in response
|
||||
- `stream` (optional): Enable streaming responses
|
||||
|
||||
**Yao-Specific Parameters:**
|
||||
|
||||
- `content` (required): The user's message or question (simplified input)
|
||||
- `chat_id` (optional): Chat session identifier (auto-generated if not provided)
|
||||
- `assistant_id` (optional): Specific assistant to use (defaults to system default)
|
||||
- `context` (optional): Additional context for the conversation
|
||||
- `silent` (optional): Silent mode flag ("true"/"false" or "1"/"0")
|
||||
- `history_visible` (optional): Whether chat history is visible ("true"/"false" or "1"/"0")
|
||||
- `client_type` (optional): Client type identifier for customization
|
||||
|
||||
**Headers:**
|
||||
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Response Headers:**
|
||||
|
||||
```
|
||||
Content-Type: text/event-stream;charset=utf-8
|
||||
Cache-Control: no-cache
|
||||
Connection: keep-alive
|
||||
```
|
||||
|
||||
**Example GET Request (Yao Simplified Format):**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/chat/completions?content=Hello%2C%20how%20are%20you%3F&chat_id=chat_123&assistant_id=mohe" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
**Example POST Request (OpenAI Compatible Format):**
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/chat/completions" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "mohe",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello, how are you?"}
|
||||
],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
**Example POST Request (Yao Simplified Format):**
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/chat/completions" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-H "Accept: text/event-stream" \
|
||||
-d "content=Hello, how are you?&chat_id=chat_123&assistant_id=mohe"
|
||||
```
|
||||
|
||||
**Response (Server-Sent Events):**
|
||||
|
||||
The response is streamed as Server-Sent Events with OpenAI-compatible format:
|
||||
|
||||
```
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1640995200,"model":"mohe","choices":[{"index":0,"delta":{"content":"Hello! I'm doing well, thank you for asking."},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1640995200,"model":"mohe","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
**Response Data Types:**
|
||||
|
||||
- `chat.completion.chunk` - Streaming content chunks (OpenAI format)
|
||||
- `error` - Error message if something goes wrong
|
||||
- `[DONE]` - Indicates completion of the response (OpenAI format)
|
||||
|
||||
**Success Response Example (OpenAI Compatible):**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-123",
|
||||
"object": "chat.completion.chunk",
|
||||
"created": 1640995200,
|
||||
"model": "mohe",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"delta": {
|
||||
"content": "Hello! I'm an AI assistant created by Yao. How can I help you today?"
|
||||
},
|
||||
"finish_reason": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Completion Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-123",
|
||||
"object": "chat.completion.chunk",
|
||||
"created": 1640995200,
|
||||
"model": "mohe",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"delta": {},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## OpenAI Client Integration
|
||||
|
||||
### Using OpenAI Python Client
|
||||
|
||||
```python
|
||||
import openai
|
||||
|
||||
# Configure client for Yao API
|
||||
openai.api_base = "https://your-yao-server.com/v1"
|
||||
openai.api_key = "your-oauth-token"
|
||||
|
||||
# Use exactly like OpenAI
|
||||
response = openai.ChatCompletion.create(
|
||||
model="mohe",
|
||||
messages=[
|
||||
{"role": "user", "content": "Hello, how are you?"}
|
||||
],
|
||||
stream=True
|
||||
)
|
||||
|
||||
for chunk in response:
|
||||
if chunk.choices[0].delta.get("content"):
|
||||
print(chunk.choices[0].delta.content, end="")
|
||||
```
|
||||
|
||||
### Using OpenAI Node.js Client
|
||||
|
||||
```javascript
|
||||
import OpenAI from "openai";
|
||||
|
||||
const openai = new OpenAI({
|
||||
baseURL: "https://your-yao-server.com/v1",
|
||||
apiKey: "your-oauth-token",
|
||||
});
|
||||
|
||||
const stream = await openai.chat.completions.create({
|
||||
model: "mohe",
|
||||
messages: [{ role: "user", content: "Hello, how are you?" }],
|
||||
stream: true,
|
||||
});
|
||||
|
||||
for await (const chunk of stream) {
|
||||
process.stdout.write(chunk.choices[0]?.delta?.content || "");
|
||||
}
|
||||
```
|
||||
|
||||
### Using OpenAI Go Client
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"io"
|
||||
|
||||
"github.com/sashabaranov/go-openai"
|
||||
)
|
||||
|
||||
func main() {
|
||||
config := openai.DefaultConfig("your-oauth-token")
|
||||
config.BaseURL = "https://your-yao-server.com/v1"
|
||||
client := openai.NewClientWithConfig(config)
|
||||
|
||||
req := openai.ChatCompletionRequest{
|
||||
Model: "mohe",
|
||||
Messages: []openai.ChatCompletionMessage{
|
||||
{
|
||||
Role: openai.ChatMessageRoleUser,
|
||||
Content: "Hello, how are you?",
|
||||
},
|
||||
},
|
||||
Stream: true,
|
||||
}
|
||||
|
||||
stream, err := client.CreateChatCompletionStream(context.Background(), req)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer stream.Close()
|
||||
|
||||
for {
|
||||
response, err := stream.Recv()
|
||||
if err == io.EOF {
|
||||
break
|
||||
}
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Print(response.Choices[0].Delta.Content)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters in Detail
|
||||
|
||||
### Content Parameter (Yao Extension)
|
||||
|
||||
The `content` parameter provides simplified input for basic use cases:
|
||||
|
||||
- **Required** for simplified Yao format
|
||||
- Can be a question, command, or conversation message
|
||||
- Supports natural language input
|
||||
- Alternative to OpenAI's `messages` array format
|
||||
|
||||
### Model/Assistant Selection
|
||||
|
||||
The `model` parameter (OpenAI) or `assistant_id` parameter (Yao) selects the AI assistant:
|
||||
|
||||
- **OpenAI Compatible**: Use `model` field in JSON requests
|
||||
- **Yao Extension**: Use `assistant_id` for URL parameters
|
||||
- **Available Models**: `mohe`, `developer`, `analyst`, etc.
|
||||
- **Default**: System default assistant if not specified
|
||||
|
||||
### Chat ID Management (Yao Extension)
|
||||
|
||||
The `chat_id` parameter manages conversation continuity:
|
||||
|
||||
- **Auto-generated** if not provided (format: `chat_{timestamp}`)
|
||||
- **Persistent** across multiple requests for the same conversation
|
||||
- **Unique** identifier for each chat session
|
||||
- **Yao-specific**: Not part of standard OpenAI API
|
||||
|
||||
### Context and Behavior (Yao Extensions)
|
||||
|
||||
Additional Yao-specific parameters for fine-tuning behavior:
|
||||
|
||||
- `context` - Provides additional context for better responses
|
||||
- `silent` - Controls verbose/quiet response modes
|
||||
- `history_visible` - Controls whether conversation history affects responses
|
||||
- `client_type` - Allows client-specific customizations
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return standardized error responses compatible with OpenAI format:
|
||||
|
||||
**Server-Sent Events Error:**
|
||||
|
||||
```
|
||||
data: {"error":{"type":"invalid_request_error","message":"content is required","code":"missing_parameter"}}
|
||||
```
|
||||
|
||||
**HTTP Error Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "The request is missing required parameters",
|
||||
"code": "missing_parameter"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Common Error Types:**
|
||||
|
||||
- `invalid_request_error` - Missing required parameters
|
||||
- `authentication_error` - Authentication failure
|
||||
- `not_found_error` - Invalid model/assistant ID
|
||||
- `internal_server_error` - Server processing error
|
||||
|
||||
**HTTP Status Codes:**
|
||||
|
||||
- `200` - Success (streaming response)
|
||||
- `400` - Bad Request (invalid parameters)
|
||||
- `401` - Unauthorized (authentication required)
|
||||
- `404` - Not Found (model not found)
|
||||
- `500` - Internal Server Error
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### OpenAI Client Migration
|
||||
|
||||
**Before (OpenAI):**
|
||||
|
||||
```python
|
||||
import openai
|
||||
|
||||
openai.api_key = "sk-..."
|
||||
response = openai.ChatCompletion.create(
|
||||
model="gpt-3.5-turbo",
|
||||
messages=[{"role": "user", "content": "Hello"}]
|
||||
)
|
||||
```
|
||||
|
||||
**After (Yao - No Code Changes Required):**
|
||||
|
||||
```python
|
||||
import openai
|
||||
|
||||
openai.api_base = "https://your-yao.com/v1" # Only change needed
|
||||
openai.api_key = "your-oauth-token" # Only change needed
|
||||
response = openai.ChatCompletion.create(
|
||||
model="mohe", # Use Yao assistant
|
||||
messages=[{"role": "user", "content": "Hello"}]
|
||||
)
|
||||
```
|
||||
|
||||
### Simple Chat Interaction
|
||||
|
||||
1. **Start a conversation (Yao simplified format):**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/chat/completions?content=What%20is%20Yao?" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
2. **Continue the conversation (OpenAI format):**
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/chat/completions" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "mohe",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Tell me more about its features"}
|
||||
],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
### Assistant-Specific Interaction
|
||||
|
||||
1. **Use a specific assistant (OpenAI compatible):**
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/chat/completions" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "developer",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Help me debug this code"}
|
||||
],
|
||||
"stream": true,
|
||||
"temperature": 0.7
|
||||
}'
|
||||
```
|
||||
|
||||
### Context-Aware Conversation (Yao Extensions)
|
||||
|
||||
1. **Provide additional context:**
|
||||
|
||||
```bash
|
||||
curl -X GET "/v1/chat/completions?content=Optimize%20this%20query&context=PostgreSQL%20database%20with%20large%20user%20table&assistant_id=analyst" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
## Client Library Examples
|
||||
|
||||
### Curl (OpenAI Format)
|
||||
|
||||
```bash
|
||||
curl -X POST "/v1/chat/completions" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "mohe",
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "Hello!"}
|
||||
],
|
||||
"stream": true,
|
||||
"max_tokens": 150,
|
||||
"temperature": 0.7
|
||||
}'
|
||||
```
|
||||
|
||||
### JavaScript (Fetch API)
|
||||
|
||||
```javascript
|
||||
const response = await fetch("/v1/chat/completions", {
|
||||
method: "POST",
|
||||
headers: {
|
||||
Authorization: `Bearer ${accessToken}`,
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
model: "mohe",
|
||||
messages: [{ role: "user", content: "Hello, how are you?" }],
|
||||
stream: true,
|
||||
}),
|
||||
});
|
||||
|
||||
const reader = response.body.getReader();
|
||||
const decoder = new TextDecoder();
|
||||
|
||||
while (true) {
|
||||
const { done, value } = await reader.read();
|
||||
if (done) break;
|
||||
|
||||
const chunk = decoder.decode(value);
|
||||
const lines = chunk.split("\n");
|
||||
|
||||
for (const line of lines) {
|
||||
if (line.startsWith("data: ")) {
|
||||
const data = line.slice(6);
|
||||
if (data === "[DONE]") return;
|
||||
|
||||
try {
|
||||
const parsed = JSON.parse(data);
|
||||
const content = parsed.choices[0]?.delta?.content;
|
||||
if (content) {
|
||||
console.log(content);
|
||||
}
|
||||
} catch (e) {
|
||||
// Skip invalid JSON
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### From OpenAI API
|
||||
|
||||
**No code changes required!** Just update your configuration:
|
||||
|
||||
1. **Change Base URL**: `https://api.openai.com/v1` → `https://your-yao.com/v1`
|
||||
2. **Update API Key**: Use your Yao OAuth token instead of OpenAI API key
|
||||
3. **Change Model Names**: `gpt-3.5-turbo` → `mohe`, `gpt-4` → `developer`, etc.
|
||||
|
||||
### From Custom Chat APIs
|
||||
|
||||
If migrating from other chat APIs, you can use Yao's simplified format:
|
||||
|
||||
- **Simple GET requests** with `content` parameter
|
||||
- **Form data POST** for basic interactions
|
||||
- **Gradual migration** to full OpenAI format
|
||||
|
||||
## Integration Considerations
|
||||
|
||||
### Performance
|
||||
|
||||
- **Streaming responses** reduce perceived latency
|
||||
- **Connection pooling** for multiple concurrent chats
|
||||
- **Automatic session cleanup** prevents memory leaks
|
||||
- **OpenAI client optimizations** work seamlessly
|
||||
|
||||
### Security
|
||||
|
||||
- **OAuth 2.1 authentication** required for all requests
|
||||
- **Session-based access control**
|
||||
- **Input validation** and sanitization
|
||||
- **Rate limiting** (configured at server level)
|
||||
- **Compatible with OpenAI security practices**
|
||||
|
||||
### Scalability
|
||||
|
||||
- **Stateless design** (session data in external store)
|
||||
- **Load balancer compatible** (sticky sessions not required)
|
||||
- **Horizontal scaling** support
|
||||
- **OpenAI client connection pooling** supported
|
||||
|
||||
## Development Notes
|
||||
|
||||
**Important:** This is a temporary implementation for full-process testing. The interface design and functionality may undergo significant global changes in future versions. However, **OpenAI compatibility will be maintained** to ensure existing client libraries continue to work.
|
||||
|
||||
### Current Limitations
|
||||
|
||||
- Limited error recovery mechanisms
|
||||
- Basic assistant selection logic
|
||||
- Simplified context management
|
||||
- Minimal response formatting options
|
||||
|
||||
### Future Enhancements
|
||||
|
||||
Future versions will maintain OpenAI compatibility while adding:
|
||||
|
||||
- Enhanced context management
|
||||
- Advanced assistant capabilities
|
||||
- Improved error handling
|
||||
- Extended Yao-specific parameters
|
||||
- WebSocket support as alternative to SSE
|
||||
|
||||
### Compatibility Promise
|
||||
|
||||
- **OpenAI Client Support**: All major OpenAI client libraries will continue to work
|
||||
- **Standard Compliance**: Full compliance with OpenAI API specification
|
||||
- **Seamless Migration**: Existing OpenAI code works with minimal configuration changes
|
||||
|
||||
This Chat API provides **100% OpenAI client compatibility** while extending capabilities with Yao-specific features, making it easy to migrate existing applications and integrate with the broader AI ecosystem.
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
package agent
|
||||
package chat
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
|
|
@ -19,8 +19,8 @@ func Attach(group *gin.RouterGroup, oauth types.OAuth) {
|
|||
group.Use(oauth.Guard)
|
||||
|
||||
// Chat Completion
|
||||
group.GET("/chat/completions", chatCompletion)
|
||||
group.POST("/chat/completions", chatCompletion)
|
||||
group.GET("/completions", chatCompletion)
|
||||
group.POST("/completions", chatCompletion)
|
||||
|
||||
}
|
||||
|
||||
|
|
@ -6,7 +6,7 @@ import (
|
|||
"github.com/gin-gonic/gin"
|
||||
"github.com/yaoapp/gou/application"
|
||||
"github.com/yaoapp/yao/config"
|
||||
"github.com/yaoapp/yao/openapi/agent"
|
||||
"github.com/yaoapp/yao/openapi/chat"
|
||||
"github.com/yaoapp/yao/openapi/dsl"
|
||||
"github.com/yaoapp/yao/openapi/file"
|
||||
"github.com/yaoapp/yao/openapi/hello"
|
||||
|
|
@ -87,8 +87,8 @@ func (openapi *OpenAPI) Attach(router *gin.Engine) {
|
|||
// Knowledge Base handlers
|
||||
kb.Attach(group.Group("/kb"), openapi.OAuth)
|
||||
|
||||
// Agent handlers
|
||||
agent.Attach(group.Group("/agent"), openapi.OAuth)
|
||||
// Chat handlers
|
||||
chat.Attach(group.Group("/chat"), openapi.OAuth)
|
||||
|
||||
// Custom handlers (Defined by developer)
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue