deepdata: core product code (backend, frontend, runtime, deepflow module)
This commit is contained in:
figmar
@@ -0,0 +1,552 @@
|
||||
# DeepFlow API Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
DeepFlow API is a comprehensive backend service for advanced research and content generation. It provides endpoints for chat-based research, text-to-speech conversion, content generation (podcasts, presentations, prose), prompt enhancement, and RAG (Retrieval-Augmented Generation) functionality.
|
||||
|
||||
**API Version:** 0.1.0
|
||||
**Base URL:** `http://localhost:8000`
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
Currently, the API does not require authentication. CORS is configured with origins defined by the `ALLOWED_ORIGINS` environment variable (default: `http://localhost:3000`).
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Chat & Research
|
||||
|
||||
#### `POST /api/chat/stream`
|
||||
|
||||
Initiates a streaming chat session with the research agent. Returns Server-Sent Events (SSE) with message chunks, tool calls, and intermediate results.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "What is quantum computing?"
|
||||
}
|
||||
],
|
||||
"thread_id": "__default__",
|
||||
"max_plan_iterations": 1,
|
||||
"max_step_num": 3,
|
||||
"max_search_results": 3,
|
||||
"auto_accepted_plan": false,
|
||||
"report_style": "ACADEMIC",
|
||||
"enable_background_investigation": true,
|
||||
"enable_deep_thinking": false,
|
||||
"enable_clarification": false
|
||||
}
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `messages` (required, array[ChatMessage]): History of messages between user and assistant
|
||||
- `resources` (optional, array[Resource]): Resources for the research
|
||||
- `thread_id` (optional, string, default: `"__default__"`): Conversation identifier
|
||||
- `max_plan_iterations` (optional, integer, default: 1): Maximum number of plan iterations
|
||||
- `max_step_num` (optional, integer, default: 3): Maximum number of steps in a plan
|
||||
- `max_search_results` (optional, integer, default: 3): Maximum number of search results
|
||||
- `auto_accepted_plan` (optional, boolean, default: false): Automatically accept the plan
|
||||
- `interrupt_feedback` (optional, string): User feedback on the plan
|
||||
- `mcp_settings` (optional, object): MCP settings (requires `ENABLE_MCP_SERVER_CONFIGURATION=true`)
|
||||
- `enable_background_investigation` (optional, boolean, default: true): Get background investigation before plan
|
||||
- `report_style` (optional, enum): Style of the report - `ACADEMIC`, `POPULAR_SCIENCE`, `NEWS`, `SOCIAL_MEDIA`, `STRATEGIC_INVESTMENT`
|
||||
- `enable_deep_thinking` (optional, boolean, default: false): Enable deep thinking
|
||||
- `enable_clarification` (optional, boolean): Enable multi-turn clarification
|
||||
- `max_clarification_rounds` (optional, integer): Maximum clarification rounds
|
||||
|
||||
**Response:**
|
||||
- Content-Type: `text/event-stream`
|
||||
- Server-sent events with various message types:
|
||||
- `message_chunk`: Raw message tokens
|
||||
- `tool_calls`: Tool invocations
|
||||
- `tool_call_chunks`: Partial tool call data
|
||||
- `tool_call_result`: Result of a tool call
|
||||
- `interrupt`: Plan interruption for user feedback
|
||||
- `error`: Error messages
|
||||
|
||||
**Example Response (Server-Sent Events):**
|
||||
```
|
||||
event: message_chunk
|
||||
data: {"thread_id":"abc123","agent":"researcher","role":"assistant","content":"I'll search for information about quantum computing..."}
|
||||
|
||||
event: tool_calls
|
||||
data: {"thread_id":"abc123","agent":"researcher","tool_calls":[{"name":"web_search","args":"{\"query\":\"quantum computing\"}"}]}
|
||||
|
||||
event: tool_call_result
|
||||
data: {"thread_id":"abc123","agent":"researcher","content":"Found 10 results about quantum computing"}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- `403`: MCP server configuration is disabled
|
||||
- `500`: Internal server error during graph execution
|
||||
|
||||
---
|
||||
|
||||
### Text-to-Speech
|
||||
|
||||
#### `POST /api/tts`
|
||||
|
||||
Converts text to speech using Volcengine TTS API.
|
||||
|
||||
**Requirements:**
|
||||
- Environment variables must be set:
|
||||
- `VOLCENGINE_TTS_APPID`
|
||||
- `VOLCENGINE_TTS_ACCESS_TOKEN`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"text": "Hello, this is a test",
|
||||
"encoding": "mp3",
|
||||
"voice_type": "BV700_V2_streaming",
|
||||
"speed_ratio": 1.0,
|
||||
"volume_ratio": 1.0,
|
||||
"pitch_ratio": 1.0,
|
||||
"text_type": "plain",
|
||||
"with_frontend": 1,
|
||||
"frontend_type": "unitTson"
|
||||
}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `text` (required, string, max 1024 chars): Text to convert to speech
|
||||
- `encoding` (optional, string, default: `"mp3"`): Audio format - `mp3`, `wav`
|
||||
- `voice_type` (optional, string, default: `"BV700_V2_streaming"`): Voice type
|
||||
- `speed_ratio` (optional, float, default: 1.0): Speech speed ratio
|
||||
- `volume_ratio` (optional, float, default: 1.0): Speech volume ratio
|
||||
- `pitch_ratio` (optional, float, default: 1.0): Speech pitch ratio
|
||||
- `text_type` (optional, string, default: `"plain"`): `plain` or `ssml`
|
||||
- `with_frontend` (optional, integer, default: 1): Enable frontend processing
|
||||
- `frontend_type` (optional, string, default: `"unitTson"`): Frontend type
|
||||
|
||||
**Response:**
|
||||
- Content-Type: `audio/mp3` or `audio/wav` (depends on encoding)
|
||||
- Binary audio data
|
||||
- Header: `Content-Disposition: attachment; filename=tts_output.{encoding}`
|
||||
|
||||
**Error Responses:**
|
||||
- `400`: Missing required environment variables
|
||||
- `500`: Internal server error during TTS processing
|
||||
|
||||
---
|
||||
|
||||
### Content Generation
|
||||
|
||||
#### `POST /api/podcast/generate`
|
||||
|
||||
Generates an audio podcast from provided text content.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"content": "# Podcast Content\nThis is the content of the podcast..."
|
||||
}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `content` (required, string): Podcast content in text format
|
||||
|
||||
**Response:**
|
||||
- Content-Type: `audio/mp3`
|
||||
- Binary audio data
|
||||
|
||||
**Error Responses:**
|
||||
- `500`: Error during podcast generation
|
||||
|
||||
---
|
||||
|
||||
#### `POST /api/ppt/generate`
|
||||
|
||||
Generates a PowerPoint presentation from provided content.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"content": "# Presentation Title\n## Slide 1\nContent here..."
|
||||
}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `content` (required, string): Content for the presentation
|
||||
|
||||
**Response:**
|
||||
- Content-Type: `application/vnd.openxmlformats-officedocument.presentationml.presentation`
|
||||
- Binary PowerPoint file (.pptx)
|
||||
- Header: `Content-Disposition: attachment; filename=output.pptx`
|
||||
|
||||
**Error Responses:**
|
||||
- `500`: Error during PPT generation
|
||||
|
||||
---
|
||||
|
||||
#### `POST /api/prose/generate`
|
||||
|
||||
Generates prose content with streaming output based on prompt and option.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"prompt": "Write a creative story about",
|
||||
"option": "story",
|
||||
"command": "make it exciting"
|
||||
}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `prompt` (required, string): Content/prompt for prose generation
|
||||
- `option` (required, string): Prose writing option
|
||||
- `command` (optional, string, default: `""`): User custom command
|
||||
|
||||
**Response:**
|
||||
- Content-Type: `text/event-stream`
|
||||
- Server-sent events with prose content chunks
|
||||
|
||||
**Example Response:**
|
||||
```
|
||||
data: "Once upon a time, there was..."
|
||||
|
||||
data: " a mysterious kingdom..."
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- `500`: Error during prose generation
|
||||
|
||||
---
|
||||
|
||||
### Prompt Enhancement
|
||||
|
||||
#### `POST /api/prompt/enhance`
|
||||
|
||||
Enhances and refines user prompts with specified report style and context.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"prompt": "Tell me about climate change",
|
||||
"context": "For a scientific audience",
|
||||
"report_style": "ACADEMIC"
|
||||
}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `prompt` (required, string): Original prompt to enhance
|
||||
- `context` (optional, string, default: `""`): Additional context about intended use
|
||||
- `report_style` (optional, string, default: `"academic"`): Style - `academic`, `popular_science`, `news`, `social_media`, `strategic_investment`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"result": "Enhanced and refined prompt here..."
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- `500`: Error during prompt enhancement
|
||||
|
||||
---
|
||||
|
||||
### MCP Integration
|
||||
|
||||
#### `POST /api/mcp/server/metadata`
|
||||
|
||||
Retrieves metadata and available tools from a Model Context Protocol (MCP) server.
|
||||
|
||||
**Requirements:**
|
||||
- Environment variable: `ENABLE_MCP_SERVER_CONFIGURATION=true`
|
||||
|
||||
**Request Body - For stdio transport:**
|
||||
```json
|
||||
{
|
||||
"transport": "stdio",
|
||||
"command": "python",
|
||||
"args": ["-m", "mcp_server"],
|
||||
"env": {
|
||||
"VAR_NAME": "value"
|
||||
},
|
||||
"timeout_seconds": 300
|
||||
}
|
||||
```
|
||||
|
||||
**Request Body - For SSE transport:**
|
||||
```json
|
||||
{
|
||||
"transport": "sse",
|
||||
"url": "https://mcp-server.example.com",
|
||||
"headers": {
|
||||
"Authorization": "Bearer token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `transport` (required, string): `stdio`, `sse`, or `streamable_http`
|
||||
- `command` (optional, string): Command to execute (stdio type)
|
||||
- `args` (optional, array[string]): Command arguments (stdio type)
|
||||
- `url` (optional, string): Server URL (sse/streamable_http type)
|
||||
- `env` (optional, object): Environment variables (stdio type)
|
||||
- `headers` (optional, object): HTTP headers (sse/streamable_http type)
|
||||
- `timeout_seconds` (optional, integer): Custom timeout in seconds (default: 300)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"transport": "stdio",
|
||||
"command": "python",
|
||||
"args": ["-m", "mcp_server"],
|
||||
"tools": [
|
||||
{
|
||||
"name": "tool_1",
|
||||
"description": "Description of tool",
|
||||
"parameters": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- `403`: MCP server configuration is disabled
|
||||
- `500`: Error retrieving MCP server metadata
|
||||
|
||||
---
|
||||
|
||||
### RAG Configuration
|
||||
|
||||
#### `GET /api/rag/config`
|
||||
|
||||
Returns the current RAG (Retrieval-Augmented Generation) provider configuration.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"provider": "ragflow"
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- None (always returns 200)
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/rag/resources`
|
||||
|
||||
Retrieves available resources from the RAG system based on optional query.
|
||||
|
||||
**Query Parameters:**
|
||||
- `query` (optional, string): Search query for resources
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"resources": [
|
||||
{
|
||||
"id": "resource_1",
|
||||
"name": "Document",
|
||||
"type": "pdf"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- None (returns empty resources array if retriever not configured)
|
||||
|
||||
---
|
||||
|
||||
### Server Configuration
|
||||
|
||||
#### `GET /api/config`
|
||||
|
||||
Returns the complete server configuration including RAG settings and available models.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"rag": {
|
||||
"provider": "ragflow"
|
||||
},
|
||||
"models": {
|
||||
"llm": ["gpt-4", "gpt-3.5-turbo"],
|
||||
"embedding": ["openai-embedding"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- None (always returns 200)
|
||||
|
||||
---
|
||||
|
||||
## Data Structures
|
||||
|
||||
### ChatMessage
|
||||
```json
|
||||
{
|
||||
"role": "user or assistant",
|
||||
"content": "string or array of ContentItem"
|
||||
}
|
||||
```
|
||||
|
||||
### ContentItem
|
||||
```json
|
||||
{
|
||||
"type": "text or image",
|
||||
"text": "string (for text type)",
|
||||
"image_url": "string (for image type)"
|
||||
}
|
||||
```
|
||||
|
||||
### ReportStyle Enum
|
||||
- `ACADEMIC`
|
||||
- `POPULAR_SCIENCE`
|
||||
- `NEWS`
|
||||
- `SOCIAL_MEDIA`
|
||||
- `STRATEGIC_INVESTMENT`
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
All endpoints follow standard HTTP status codes:
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| 200 | Success |
|
||||
| 400 | Bad Request - Invalid parameters |
|
||||
| 403 | Forbidden - Feature disabled or unauthorized |
|
||||
| 500 | Internal Server Error |
|
||||
|
||||
Error response format:
|
||||
```json
|
||||
{
|
||||
"detail": "Error message describing what went wrong"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming Responses
|
||||
|
||||
Several endpoints return streaming responses using Server-Sent Events (SSE):
|
||||
|
||||
- `/api/chat/stream` - Chat streaming
|
||||
- `/api/prose/generate` - Prose generation streaming
|
||||
|
||||
To consume SSE in your client:
|
||||
```javascript
|
||||
const eventSource = new EventSource('/api/chat/stream', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({...})
|
||||
});
|
||||
|
||||
eventSource.addEventListener('message_chunk', (event) => {
|
||||
console.log(event.data);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting & Quotas
|
||||
|
||||
Currently no rate limiting is implemented. The system respects the following limits:
|
||||
- TTS text input: max 1024 characters
|
||||
- Search results: configurable via `max_search_results`
|
||||
- Plan iterations: configurable via `max_plan_iterations`
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key environment variables for API configuration:
|
||||
|
||||
```bash
|
||||
# CORS
|
||||
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
|
||||
|
||||
# TTS
|
||||
VOLCENGINE_TTS_APPID=your_app_id
|
||||
VOLCENGINE_TTS_ACCESS_TOKEN=your_access_token
|
||||
VOLCENGINE_TTS_CLUSTER=volcano_tts
|
||||
VOLCENGINE_TTS_VOICE_TYPE=BV700_V2_streaming
|
||||
|
||||
# MCP
|
||||
ENABLE_MCP_SERVER_CONFIGURATION=false
|
||||
|
||||
# Checkpointing
|
||||
LANGGRAPH_CHECKPOINT_SAVER=false
|
||||
LANGGRAPH_CHECKPOINT_DB_URL=postgresql://user:pass@localhost/db
|
||||
|
||||
# RAG
|
||||
RAG_PROVIDER=ragflow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Chat with Research
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/chat/stream \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"messages": [{"role": "user", "content": "What are the latest AI trends?"}],
|
||||
"thread_id": "conversation_1",
|
||||
"max_search_results": 5,
|
||||
"report_style": "POPULAR_SCIENCE"
|
||||
}'
|
||||
```
|
||||
|
||||
### Example 2: Text-to-Speech
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/tts \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"text": "Hello world",
|
||||
"encoding": "mp3",
|
||||
"speed_ratio": 1.2
|
||||
}' \
|
||||
--output audio.mp3
|
||||
```
|
||||
|
||||
### Example 3: Enhance Prompt
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/prompt/enhance \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Tell me about space",
|
||||
"context": "For kids aged 8-10",
|
||||
"report_style": "POPULAR_SCIENCE"
|
||||
}'
|
||||
```
|
||||
|
||||
### Example 4: Get Server Configuration
|
||||
```bash
|
||||
curl -X GET http://localhost:8000/api/config
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
### Version 0.1.0
|
||||
- Initial API release
|
||||
- Chat streaming with research capabilities
|
||||
- Text-to-speech conversion
|
||||
- Content generation (podcasts, presentations, prose)
|
||||
- Prompt enhancement
|
||||
- MCP server integration
|
||||
- RAG configuration and resources
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about the API, please refer to the project documentation or file an issue in the repository.
|
||||
@@ -0,0 +1,317 @@
|
||||
# Debugging Guide
|
||||
|
||||
This guide helps you debug DeepFlow workflows, view model outputs, and troubleshoot common issues.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Viewing Model Output](#viewing-model-output)
|
||||
- [Debug Logging Configuration](#debug-logging-configuration)
|
||||
- [LangChain Verbose Logging](#langchain-verbose-logging)
|
||||
- [LangSmith Tracing](#langsmith-tracing)
|
||||
- [Docker Compose Debugging](#docker-compose-debugging)
|
||||
- [Common Issues](#common-issues)
|
||||
|
||||
## Viewing Model Output
|
||||
|
||||
When you need to see the complete model output, including tool calls and internal reasoning, you have several options:
|
||||
|
||||
### 1. Enable Debug Logging
|
||||
|
||||
Set `DEBUG=True` in your `.env` file or configuration:
|
||||
|
||||
```bash
|
||||
DEBUG=True
|
||||
```
|
||||
|
||||
This enables debug-level logging throughout the application, showing detailed information about:
|
||||
- System prompts sent to LLMs
|
||||
- Model responses
|
||||
- Tool calls and results
|
||||
- Workflow state transitions
|
||||
|
||||
### 2. Enable LangChain Verbose Logging
|
||||
|
||||
Add these environment variables to your `.env` file for detailed LangChain output:
|
||||
|
||||
```bash
|
||||
# Enable verbose logging for LangChain
|
||||
LANGCHAIN_VERBOSE=true
|
||||
LANGCHAIN_DEBUG=true
|
||||
```
|
||||
|
||||
This will show:
|
||||
- Chain execution steps
|
||||
- LLM input/output for each call
|
||||
- Tool invocations
|
||||
- Intermediate results
|
||||
|
||||
### 3. Enable LangSmith Tracing (Recommended for Production)
|
||||
|
||||
For advanced debugging and visualization, configure LangSmith integration:
|
||||
|
||||
```bash
|
||||
LANGSMITH_TRACING=true
|
||||
LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
|
||||
LANGSMITH_API_KEY="your-api-key"
|
||||
LANGSMITH_PROJECT="your-project-name"
|
||||
```
|
||||
|
||||
LangSmith provides:
|
||||
- Visual trace of workflow execution
|
||||
- Performance metrics
|
||||
- Token usage statistics
|
||||
- Error tracking
|
||||
- Comparison between runs
|
||||
|
||||
To get started with LangSmith:
|
||||
1. Sign up at [LangSmith](https://smith.langchain.com/)
|
||||
2. Create a project
|
||||
3. Copy your API key
|
||||
4. Add the configuration to your `.env` file
|
||||
|
||||
## Debug Logging Configuration
|
||||
|
||||
### Log Levels
|
||||
|
||||
DeepFlow uses Python's standard logging levels:
|
||||
|
||||
- **DEBUG**: Detailed diagnostic information
|
||||
- **INFO**: General informational messages
|
||||
- **WARNING**: Warning messages
|
||||
- **ERROR**: Error messages
|
||||
- **CRITICAL**: Critical errors
|
||||
|
||||
### Viewing Logs
|
||||
|
||||
**Development mode (console):**
|
||||
```bash
|
||||
uv run main.py
|
||||
```
|
||||
|
||||
Logs will be printed to the console.
|
||||
|
||||
**Docker Compose:**
|
||||
```bash
|
||||
# View logs from all services
|
||||
docker compose logs -f
|
||||
|
||||
# View logs from backend only
|
||||
docker compose logs -f backend
|
||||
|
||||
# View logs with timestamps
|
||||
docker compose logs -f --timestamps
|
||||
```
|
||||
|
||||
## LangChain Verbose Logging
|
||||
|
||||
### What It Shows
|
||||
|
||||
When `LANGCHAIN_VERBOSE=true` is enabled, you'll see output like:
|
||||
|
||||
```
|
||||
> Entering new AgentExecutor chain...
|
||||
Thought: I need to search for information about quantum computing
|
||||
Action: web_search
|
||||
Action Input: "quantum computing basics 2024"
|
||||
|
||||
Observation: [Search results...]
|
||||
|
||||
Thought: I now have enough information to answer
|
||||
Final Answer: ...
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
```bash
|
||||
# Basic verbose mode
|
||||
LANGCHAIN_VERBOSE=true
|
||||
|
||||
# Full debug mode with internal details
|
||||
LANGCHAIN_DEBUG=true
|
||||
|
||||
# Both (recommended for debugging)
|
||||
LANGCHAIN_VERBOSE=true
|
||||
LANGCHAIN_DEBUG=true
|
||||
```
|
||||
|
||||
## LangSmith Tracing
|
||||
|
||||
### Setup
|
||||
|
||||
1. **Create a LangSmith account**: Visit [smith.langchain.com](https://smith.langchain.com)
|
||||
|
||||
2. **Get your API key**: Navigate to Settings → API Keys
|
||||
|
||||
3. **Configure environment variables**:
|
||||
```bash
|
||||
LANGSMITH_TRACING=true
|
||||
LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
|
||||
LANGSMITH_API_KEY="lsv2_pt_..."
|
||||
LANGSMITH_PROJECT="deepflow-debug"
|
||||
```
|
||||
|
||||
4. **Restart your application**
|
||||
|
||||
### Features
|
||||
|
||||
- **Visual traces**: See the entire workflow execution as a graph
|
||||
- **Performance metrics**: Identify slow operations
|
||||
- **Token tracking**: Monitor LLM token usage
|
||||
- **Error analysis**: Quickly identify failures
|
||||
- **Comparison**: Compare different runs side-by-side
|
||||
|
||||
### Viewing Traces
|
||||
|
||||
1. Run your workflow as normal
|
||||
2. Visit [smith.langchain.com](https://smith.langchain.com)
|
||||
3. Select your project
|
||||
4. View traces in the "Traces" tab
|
||||
|
||||
## Docker Compose Debugging
|
||||
|
||||
### Update docker-compose.yml
|
||||
|
||||
Add debug environment variables to your `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
backend:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
environment:
|
||||
# Debug settings
|
||||
- DEBUG=True
|
||||
- LANGCHAIN_VERBOSE=true
|
||||
- LANGCHAIN_DEBUG=true
|
||||
|
||||
# LangSmith (optional)
|
||||
- LANGSMITH_TRACING=true
|
||||
- LANGSMITH_ENDPOINT=https://api.smith.langchain.com
|
||||
- LANGSMITH_API_KEY=${LANGSMITH_API_KEY}
|
||||
- LANGSMITH_PROJECT=${LANGSMITH_PROJECT}
|
||||
```
|
||||
|
||||
### View Detailed Logs
|
||||
|
||||
```bash
|
||||
# Start with verbose output
|
||||
docker compose up
|
||||
|
||||
# Or in detached mode and follow logs
|
||||
docker compose up -d
|
||||
docker compose logs -f backend
|
||||
```
|
||||
|
||||
### Common Docker Commands
|
||||
|
||||
```bash
|
||||
# View logs from last 100 lines
|
||||
docker compose logs --tail=100 backend
|
||||
|
||||
# View logs with timestamps
|
||||
docker compose logs -f --timestamps
|
||||
|
||||
# Check container status
|
||||
docker compose ps
|
||||
|
||||
# Restart services
|
||||
docker compose restart backend
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: "Log information doesn't show complete content"
|
||||
|
||||
**Solution**: Enable debug logging as described above:
|
||||
```bash
|
||||
DEBUG=True
|
||||
LANGCHAIN_VERBOSE=true
|
||||
LANGCHAIN_DEBUG=true
|
||||
```
|
||||
|
||||
### Issue: "Can't see system prompts"
|
||||
|
||||
**Solution**: Debug logging will show system prompts. Look for log entries like:
|
||||
```
|
||||
[INFO] System Prompt:
|
||||
You are DeepFlow, a friendly AI assistant...
|
||||
```
|
||||
|
||||
### Issue: "Want to see token usage"
|
||||
|
||||
**Solution**: Enable LangSmith tracing or check model responses in verbose mode:
|
||||
```bash
|
||||
LANGCHAIN_VERBOSE=true
|
||||
```
|
||||
|
||||
### Issue: "Need to debug specific nodes"
|
||||
|
||||
**Solution**: Add custom logging in specific nodes. For example, in `src/graph/nodes.py`:
|
||||
```python
|
||||
import logging
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
def my_node(state, config):
|
||||
logger.debug(f"Node input: {state}")
|
||||
# ... your code ...
|
||||
logger.debug(f"Node output: {result}")
|
||||
return result
|
||||
```
|
||||
|
||||
### Issue: "Logs are too verbose"
|
||||
|
||||
**Solution**: Adjust log level for specific modules:
|
||||
```python
|
||||
# In your code
|
||||
logging.getLogger('langchain').setLevel(logging.WARNING)
|
||||
logging.getLogger('openai').setLevel(logging.WARNING)
|
||||
```
|
||||
|
||||
## Performance Debugging
|
||||
|
||||
### Measure Execution Time
|
||||
|
||||
Enable LangSmith or add timing logs:
|
||||
|
||||
```python
|
||||
import time
|
||||
start = time.time()
|
||||
result = some_function()
|
||||
logger.info(f"Execution time: {time.time() - start:.2f}s")
|
||||
```
|
||||
|
||||
### Monitor Token Usage
|
||||
|
||||
With LangSmith enabled, token usage is automatically tracked. Alternatively, check model responses:
|
||||
|
||||
```bash
|
||||
LANGCHAIN_VERBOSE=true
|
||||
```
|
||||
|
||||
Look for output like:
|
||||
```
|
||||
Tokens Used: 150
|
||||
Prompt Tokens: 100
|
||||
Completion Tokens: 50
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [LangSmith Documentation](https://docs.smith.langchain.com/)
|
||||
- [LangGraph Debugging](https://langchain-ai.github.io/langgraph/how-tos/debugging/)
|
||||
- [Configuration Guide](./configuration_guide.md)
|
||||
- [API Documentation](./API.md)
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're still experiencing issues:
|
||||
|
||||
1. Check existing [GitHub Issues](https://github.com/bytedance/deepflow/issues)
|
||||
2. Enable debug logging and LangSmith tracing
|
||||
3. Collect relevant log output
|
||||
4. Create a new issue with:
|
||||
- Description of the problem
|
||||
- Steps to reproduce
|
||||
- Log output
|
||||
- Configuration (without sensitive data)
|
||||
@@ -0,0 +1,94 @@
|
||||
# FAQ
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Where's the name DeepFlow come from?](#wheres-the-name-deepflow-come-from)
|
||||
- [Which models does DeepFlow support?](#which-models-does-deepflow-support)
|
||||
- [How do I view complete model output?](#how-do-i-view-complete-model-output)
|
||||
- [How do I enable debug logging?](#how-do-i-enable-debug-logging)
|
||||
- [How do I troubleshoot issues?](#how-do-i-troubleshoot-issues)
|
||||
|
||||
## Where's the name DeepFlow come from?
|
||||
|
||||
DeepFlow is short for **D**eep **E**xploration and **E**fficient **R**esearch **Flow**. It is named after the deer, which is a symbol of gentleness and elegance. We hope DeepFlow can bring a gentle and elegant deep research experience to you.
|
||||
|
||||
## Which models does DeepFlow support?
|
||||
|
||||
Please refer to the [Configuration Guide](configuration_guide.md) for more details.
|
||||
|
||||
## How do I view complete model output?
|
||||
|
||||
If you want to see the complete model output, including system prompts, tool calls, and LLM responses:
|
||||
|
||||
1. **Enable debug logging** by setting `DEBUG=True` in your `.env` file
|
||||
|
||||
2. **Enable LangChain verbose logging** by adding these to your `.env`:
|
||||
|
||||
```bash
|
||||
LANGCHAIN_VERBOSE=true
|
||||
LANGCHAIN_DEBUG=true
|
||||
```
|
||||
|
||||
3. **Use LangSmith tracing** for visual debugging (recommended for production):
|
||||
|
||||
```bash
|
||||
LANGSMITH_TRACING=true
|
||||
LANGSMITH_API_KEY="your-api-key"
|
||||
LANGSMITH_PROJECT="your-project-name"
|
||||
```
|
||||
|
||||
For detailed instructions, see the [Debugging Guide](DEBUGGING.md).
|
||||
|
||||
## How do I enable debug logging?
|
||||
|
||||
To enable debug logging:
|
||||
|
||||
1. Open your `.env` file
|
||||
2. Set `DEBUG=True`
|
||||
3. Restart your application
|
||||
|
||||
For Docker Compose:
|
||||
|
||||
```bash
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
For development:
|
||||
|
||||
```bash
|
||||
uv run main.py
|
||||
```
|
||||
|
||||
You'll now see detailed logs including:
|
||||
|
||||
- System prompts sent to LLMs
|
||||
- Model responses
|
||||
- Tool execution details
|
||||
- Workflow state transitions
|
||||
|
||||
See the [Debugging Guide](DEBUGGING.md) for more options.
|
||||
|
||||
## How do I troubleshoot issues?
|
||||
|
||||
When encountering issues:
|
||||
|
||||
1. **Check the logs**: Enable debug logging as described above
|
||||
2. **Review configuration**: Ensure your `.env` and `conf.yaml` are correct
|
||||
3. **Check existing issues**: Search [GitHub Issues](https://github.com/bytedance/deepflow/issues) for similar problems
|
||||
4. **Enable verbose logging**: Use `LANGCHAIN_VERBOSE=true` for detailed output
|
||||
5. **Use LangSmith**: For visual debugging, enable LangSmith tracing
|
||||
|
||||
For Docker-specific issues:
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
docker compose logs -f
|
||||
|
||||
# Check container status
|
||||
docker compose ps
|
||||
|
||||
# Restart services
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
For more detailed troubleshooting steps, see the [Debugging Guide](DEBUGGING.md).
|
||||
@@ -0,0 +1,354 @@
|
||||
# Configuration Guide
|
||||
|
||||
## Quick Settings
|
||||
|
||||
Copy the `conf.yaml.example` file to `conf.yaml` and modify the configurations to match your specific settings and requirements.
|
||||
|
||||
```bash
|
||||
cd deepflow
|
||||
cp conf.yaml.example conf.yaml
|
||||
```
|
||||
|
||||
## Which models does DeepFlow support?
|
||||
|
||||
In DeepFlow, we currently only support non-reasoning models. This means models like OpenAI's o1/o3 or DeepSeek's R1 are not supported yet, but we plan to add support for them in the future. Additionally, all Gemma-3 models are currently unsupported due to the lack of tool usage capabilities.
|
||||
|
||||
### Supported Models
|
||||
|
||||
`doubao-1.5-pro-32k-250115`, `gpt-4o`, `qwen-max-latest`,`qwen3-235b-a22b`,`qwen3-coder`, `gemini-2.0-flash`, `deepseek-v3`, and theoretically any other non-reasoning chat models that implement the OpenAI API specification.
|
||||
|
||||
### Local Model Support
|
||||
|
||||
DeepFlow supports local models through OpenAI-compatible APIs:
|
||||
|
||||
- **Ollama**: `http://localhost:11434/v1` (tested and supported for local development)
|
||||
|
||||
See the `conf.yaml.example` file for detailed configuration examples.
|
||||
|
||||
> [!NOTE]
|
||||
> The Deep Research process requires the model to have a **longer context window**, which is not supported by all models.
|
||||
> A work-around is to set the `Max steps of a research plan` to `2` in the settings dialog located on the top right corner of the web page,
|
||||
> or set `max_step_num` to `2` when invoking the API.
|
||||
|
||||
### How to switch models?
|
||||
You can switch the model in use by modifying the `conf.yaml` file in the root directory of the project, using the configuration in the [litellm format](https://docs.litellm.ai/docs/providers/openai_compatible).
|
||||
|
||||
---
|
||||
|
||||
### How to use OpenAI-Compatible models?
|
||||
|
||||
DeepFlow supports integration with OpenAI-Compatible models, which are models that implement the OpenAI API specification. This includes various open-source and commercial models that provide API endpoints compatible with the OpenAI format. You can refer to [litellm OpenAI-Compatible](https://docs.litellm.ai/docs/providers/openai_compatible) for detailed documentation.
|
||||
The following is a configuration example of `conf.yaml` for using OpenAI-Compatible models:
|
||||
|
||||
```yaml
|
||||
# An example of Doubao models served by VolcEngine
|
||||
BASIC_MODEL:
|
||||
base_url: "https://ark.cn-beijing.volces.com/api/v3"
|
||||
model: "doubao-1.5-pro-32k-250115"
|
||||
api_key: YOUR_API_KEY
|
||||
|
||||
# An example of Aliyun models
|
||||
BASIC_MODEL:
|
||||
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
model: "qwen-max-latest"
|
||||
api_key: YOUR_API_KEY
|
||||
|
||||
# An example of deepseek official models
|
||||
BASIC_MODEL:
|
||||
base_url: "https://api.deepseek.com"
|
||||
model: "deepseek-chat"
|
||||
api_key: YOUR_API_KEY
|
||||
|
||||
# An example of Google Gemini models using OpenAI-Compatible interface
|
||||
BASIC_MODEL:
|
||||
base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
|
||||
model: "gemini-2.0-flash"
|
||||
api_key: YOUR_API_KEY
|
||||
```
|
||||
The following is a configuration example of `conf.yaml` for using best opensource OpenAI-Compatible models:
|
||||
```yaml
|
||||
# Use latest deepseek-v3 to handle basic tasks, the open source SOTA model for basic tasks
|
||||
BASIC_MODEL:
|
||||
base_url: https://api.deepseek.com
|
||||
model: "deepseek-v3"
|
||||
api_key: YOUR_API_KEY
|
||||
temperature: 0.6
|
||||
top_p: 0.90
|
||||
# Use qwen3-235b-a22b to handle reasoning tasks, the open source SOTA model for reasoning
|
||||
REASONING_MODEL:
|
||||
base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
model: "qwen3-235b-a22b-thinking-2507"
|
||||
api_key: YOUR_API_KEY
|
||||
temperature: 0.6
|
||||
top_p: 0.90
|
||||
# Use qwen3-coder-480b-a35b-instruct to handle coding tasks, the open source SOTA model for coding
|
||||
CODE_MODEL:
|
||||
base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
model: "qwen3-coder-480b-a35b-instruct"
|
||||
api_key: YOUR_API_KEY
|
||||
temperature: 0.6
|
||||
top_p: 0.90
|
||||
```
|
||||
In addition, you need to set the `AGENT_LLM_MAP` in `src/config/agents.py` to use the correct model for each agent. For example:
|
||||
|
||||
```python
|
||||
# Define agent-LLM mapping
|
||||
AGENT_LLM_MAP: dict[str, LLMType] = {
|
||||
"coordinator": "reasoning",
|
||||
"planner": "reasoning",
|
||||
"researcher": "reasoning",
|
||||
"coder": "basic",
|
||||
"reporter": "basic",
|
||||
"podcast_script_writer": "basic",
|
||||
"ppt_composer": "basic",
|
||||
"prose_writer": "basic",
|
||||
"prompt_enhancer": "basic",
|
||||
}
|
||||
|
||||
|
||||
### How to use Google AI Studio models?
|
||||
|
||||
DeepFlow supports native integration with Google AI Studio (formerly Google Generative AI) API. This provides direct access to Google's Gemini models with their full feature set and optimized performance.
|
||||
|
||||
To use Google AI Studio models, you need to:
|
||||
1. Get your API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
|
||||
2. Set the `platform` field to `"google_aistudio"` in your configuration
|
||||
3. Configure your model and API key
|
||||
|
||||
The following is a configuration example for using Google AI Studio models:
|
||||
|
||||
```yaml
|
||||
# Google AI Studio native API (recommended for Google models)
|
||||
BASIC_MODEL:
|
||||
platform: "google_aistudio"
|
||||
model: "gemini-2.5-flash" # or "gemini-1.5-pro" ,...
|
||||
api_key: YOUR_GOOGLE_API_KEY # Get from https://aistudio.google.com/app/apikey
|
||||
|
||||
```
|
||||
|
||||
**Note:** The `platform: "google_aistudio"` field is required to distinguish from other providers that may offer Gemini models through OpenAI-compatible APIs.
|
||||
```
|
||||
|
||||
### How to use models with self-signed SSL certificates?
|
||||
|
||||
If your LLM server uses self-signed SSL certificates, you can disable SSL certificate verification by adding the `verify_ssl: false` parameter to your model configuration:
|
||||
|
||||
```yaml
|
||||
BASIC_MODEL:
|
||||
base_url: "https://your-llm-server.com/api/v1"
|
||||
model: "your-model-name"
|
||||
api_key: YOUR_API_KEY
|
||||
verify_ssl: false # Disable SSL certificate verification for self-signed certificates
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> Disabling SSL certificate verification reduces security and should only be used in development environments or when you trust the LLM server. In production environments, it's recommended to use properly signed SSL certificates.
|
||||
|
||||
### How to use Ollama models?
|
||||
|
||||
DeepFlow supports the integration of Ollama models. You can refer to [litellm Ollama](https://docs.litellm.ai/docs/providers/ollama). <br>
|
||||
The following is a configuration example of `conf.yaml` for using Ollama models(you might need to run the 'ollama serve' first):
|
||||
|
||||
```yaml
|
||||
BASIC_MODEL:
|
||||
model: "model-name" # Model name, which supports the completions API(important), such as: qwen3:8b, mistral-small3.1:24b, qwen2.5:3b
|
||||
base_url: "http://localhost:11434/v1" # Local service address of Ollama, which can be started/viewed via ollama serve
|
||||
api_key: "whatever" # Mandatory, fake api_key with a random string you like :-)
|
||||
```
|
||||
|
||||
### How to use OpenRouter models?
|
||||
|
||||
DeepFlow supports the integration of OpenRouter models. You can refer to [litellm OpenRouter](https://docs.litellm.ai/docs/providers/openrouter). To use OpenRouter models, you need to:
|
||||
1. Obtain the OPENROUTER_API_KEY from OpenRouter (https://openrouter.ai/) and set it in the environment variable.
|
||||
2. Add the `openrouter/` prefix before the model name.
|
||||
3. Configure the correct OpenRouter base URL.
|
||||
|
||||
The following is a configuration example for using OpenRouter models:
|
||||
1. Configure OPENROUTER_API_KEY in the environment variable (such as the `.env` file)
|
||||
```ini
|
||||
OPENROUTER_API_KEY=""
|
||||
```
|
||||
2. Set the model name in `conf.yaml`
|
||||
```yaml
|
||||
BASIC_MODEL:
|
||||
model: "openrouter/google/palm-2-chat-bison"
|
||||
```
|
||||
|
||||
Note: The available models and their exact names may change over time. Please verify the currently available models and their correct identifiers in [OpenRouter's official documentation](https://openrouter.ai/docs).
|
||||
|
||||
|
||||
### How to use Azure OpenAI chat models?
|
||||
|
||||
DeepFlow supports the integration of Azure OpenAI chat models. You can refer to [AzureChatOpenAI](https://python.langchain.com/api_reference/openai/chat_models/langchain_openai.chat_models.azure.AzureChatOpenAI.html). Configuration example of `conf.yaml`:
|
||||
```yaml
|
||||
BASIC_MODEL:
|
||||
model: "azure/gpt-4o-2024-08-06"
|
||||
azure_endpoint: $AZURE_OPENAI_ENDPOINT
|
||||
api_version: $OPENAI_API_VERSION
|
||||
api_key: $AZURE_OPENAI_API_KEY
|
||||
```
|
||||
|
||||
### How to configure context length for different models
|
||||
|
||||
Different models have different context length limitations. DeepFlow provides a method to control the context length between different models. You can configure the context length between different models in the `conf.yaml` file. For example:
|
||||
```yaml
|
||||
BASIC_MODEL:
|
||||
base_url: https://ark.cn-beijing.volces.com/api/v3
|
||||
model: "doubao-1-5-pro-32k-250115"
|
||||
api_key: ""
|
||||
token_limit: 128000
|
||||
```
|
||||
This means that the context length limit using this model is 128k.
|
||||
|
||||
The context management doesn't work if the token_limit is not set.
|
||||
|
||||
## About Search Engine
|
||||
|
||||
### How to control search domains for Tavily?
|
||||
|
||||
DeepFlow allows you to control which domains are included or excluded in Tavily search results through the configuration file. This helps improve search result quality and reduce hallucinations by focusing on trusted sources.
|
||||
|
||||
`Tips`: it only supports Tavily currently.
|
||||
|
||||
You can configure domain filtering and search results in your `conf.yaml` file as follows:
|
||||
|
||||
```yaml
|
||||
SEARCH_ENGINE:
|
||||
engine: tavily
|
||||
# Only include results from these domains (whitelist)
|
||||
include_domains:
|
||||
- trusted-news.com
|
||||
- gov.org
|
||||
- reliable-source.edu
|
||||
# Exclude results from these domains (blacklist)
|
||||
exclude_domains:
|
||||
- unreliable-site.com
|
||||
- spam-domain.net
|
||||
# Include images in search results, default: true
|
||||
include_images: false
|
||||
# Include image descriptions in search results, default: true
|
||||
include_image_descriptions: false
|
||||
# Include raw content in search results, default: true
|
||||
include_raw_content: false
|
||||
```
|
||||
|
||||
### How to post-process Tavily search results
|
||||
|
||||
DeepFlow can post-process Tavily search results:
|
||||
* Remove duplicate content
|
||||
* Filter low-quality content: Filter out results with low relevance scores
|
||||
* Clear base64 encoded images
|
||||
* Length truncation: Truncate each search result according to the user-configured length
|
||||
|
||||
The filtering of low-quality content and length truncation depend on user configuration, providing two configurable parameters:
|
||||
* min_score_threshold: Minimum relevance score threshold, search results below this threshold will be filtered. If not set, no filtering will be performed;
|
||||
* max_content_length_per_page: Maximum length limit for each search result content, parts exceeding this length will be truncated. If not set, no truncation will be performed;
|
||||
|
||||
These two parameters can be configured in `conf.yaml` as shown below:
|
||||
```yaml
|
||||
SEARCH_ENGINE:
|
||||
engine: tavily
|
||||
include_images: true
|
||||
min_score_threshold: 0.4
|
||||
max_content_length_per_page: 5000
|
||||
```
|
||||
That's meaning that the search results will be filtered based on the minimum relevance score threshold and truncated to the maximum length limit for each search result content.
|
||||
|
||||
## RAG (Retrieval-Augmented Generation) Configuration
|
||||
|
||||
DeepFlow supports multiple RAG providers for document retrieval. Configure the RAG provider by setting environment variables.
|
||||
|
||||
### Supported RAG Providers
|
||||
|
||||
- **RAGFlow**: Document retrieval using RAGFlow API
|
||||
- **VikingDB Knowledge Base**: ByteDance's VikingDB knowledge base service
|
||||
- **Milvus**: Open-source vector database for similarity search
|
||||
- **Qdrant**: Open-source vector search engine with cloud and self-hosted options
|
||||
- **MOI**: Hybrid database for enterprise users
|
||||
- **Dify**: AI application platform with RAG capabilities
|
||||
|
||||
### Qdrant Configuration
|
||||
|
||||
To use Qdrant as your RAG provider, set the following environment variables:
|
||||
|
||||
```bash
|
||||
# RAG_PROVIDER: qdrant (using Qdrant Cloud or self-hosted)
|
||||
RAG_PROVIDER=qdrant
|
||||
QDRANT_LOCATION=https://xyz-example.eu-central.aws.cloud.qdrant.io:6333
|
||||
QDRANT_API_KEY=<your_qdrant_api_key>
|
||||
QDRANT_COLLECTION=documents
|
||||
QDRANT_EMBEDDING_PROVIDER=openai # support openai, dashscope
|
||||
QDRANT_EMBEDDING_BASE_URL=
|
||||
QDRANT_EMBEDDING_MODEL=text-embedding-ada-002
|
||||
QDRANT_EMBEDDING_API_KEY=<your_embedding_api_key>
|
||||
QDRANT_AUTO_LOAD_EXAMPLES=true # automatically load example markdown files
|
||||
```
|
||||
|
||||
### Milvus Configuration
|
||||
|
||||
To use Milvus as your RAG provider, set the following environment variables:
|
||||
|
||||
```bash
|
||||
# RAG_PROVIDER: milvus (using free milvus instance on zilliz cloud: https://docs.zilliz.com/docs/quick-start )
|
||||
RAG_PROVIDER=milvus
|
||||
MILVUS_URI=<endpoint_of_self_hosted_milvus_or_zilliz_cloud>
|
||||
MILVUS_USER=<username_of_self_hosted_milvus_or_zilliz_cloud>
|
||||
MILVUS_PASSWORD=<password_of_self_hosted_milvus_or_zilliz_cloud>
|
||||
MILVUS_COLLECTION=documents
|
||||
MILVUS_EMBEDDING_PROVIDER=openai
|
||||
MILVUS_EMBEDDING_BASE_URL=
|
||||
MILVUS_EMBEDDING_MODEL=
|
||||
MILVUS_EMBEDDING_API_KEY=
|
||||
|
||||
# RAG_PROVIDER: milvus (using milvus lite on Mac or Linux)
|
||||
RAG_PROVIDER=milvus
|
||||
MILVUS_URI=./milvus_demo.db
|
||||
MILVUS_COLLECTION=documents
|
||||
MILVUS_EMBEDDING_PROVIDER=openai
|
||||
MILVUS_EMBEDDING_BASE_URL=
|
||||
MILVUS_EMBEDDING_MODEL=
|
||||
MILVUS_EMBEDDING_API_KEY=
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Turn Clarification (Optional)
|
||||
|
||||
An optional feature that helps clarify vague research questions through conversation. **Disabled by default.**
|
||||
|
||||
### Enable via Command Line
|
||||
|
||||
```bash
|
||||
# Enable clarification for vague questions
|
||||
uv run main.py "Research AI" --enable-clarification
|
||||
|
||||
# Set custom maximum clarification rounds
|
||||
uv run main.py "Research AI" --enable-clarification --max-clarification-rounds 3
|
||||
|
||||
# Interactive mode with clarification
|
||||
uv run main.py --interactive --enable-clarification --max-clarification-rounds 3
|
||||
```
|
||||
|
||||
### Enable via API
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [{"role": "user", "content": "Research AI"}],
|
||||
"enable_clarification": true,
|
||||
"max_clarification_rounds": 3
|
||||
}
|
||||
```
|
||||
|
||||
### Enable via UI Settings
|
||||
|
||||
1. Open DeepFlow web interface
|
||||
2. Navigate to **Settings** → **General** tab
|
||||
3. Find **"Enable Clarification"** toggle
|
||||
4. Turn it **ON** to enable multi-turn clarification. Clarification is **disabled** by default. You need to manually enable it through any of the above methods. When clarification is enabled, you'll see **"Max Clarification Rounds"** field appear below the toggle
|
||||
6. Set the maximum number of clarification rounds (default: 3, minimum: 1)
|
||||
7. Click **Save** to apply changes
|
||||
|
||||
**When enabled**, the Coordinator will ask up to the specified number of clarifying questions for vague topics before starting research, improving report relevance and depth. The `max_clarification_rounds` parameter controls how many rounds of clarification are allowed.
|
||||
|
||||
|
||||
**Note**: The `max_clarification_rounds` parameter only takes effect when `enable_clarification` is set to `true`. If clarification is disabled, this parameter is ignored.
|
||||
@@ -0,0 +1,88 @@
|
||||
# MCP Integrations（Beta）
|
||||
|
||||
Now This feature is diabled by default. You can enable it by setting the environment ENABLE_MCP_SERVER_CONFIGURATION to be true
|
||||
|
||||
> [!WARNING]
|
||||
> Please enable this feature before securing your frond-end and back-end in a managed environment.
|
||||
> Otherwise, you system could be compromised.
|
||||
|
||||
This feature is diabled by default. You can enable it by setting the environment ENABLE_MCP_SERVER_CONFIGURATION
|
||||
Please enable this feature before securing your frond-end and back-end in an internal environment.q
|
||||
|
||||
## Example of MCP Server Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-github-trending": {
|
||||
"transport": "stdio",
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-github-trending"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## APIs
|
||||
|
||||
### Get metadata of MCP Server
|
||||
|
||||
**POST /api/mcp/server/metadata**
|
||||
|
||||
For `stdio` type:
|
||||
```json
|
||||
{
|
||||
"transport": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "tavily-mcp@0.1.3"],
|
||||
"env": {"TAVILY_API_KEY": "tvly-dev-xxx"}
|
||||
}
|
||||
```
|
||||
|
||||
For `sse` type:
|
||||
```json
|
||||
{
|
||||
"transport": "sse",
|
||||
"url": "http://localhost:3000/sse",
|
||||
"headers": {
|
||||
"API_KEY": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For `streamable_http` type:
|
||||
```json
|
||||
{
|
||||
"transport": "streamable_http",
|
||||
"url": "http://localhost:3000/mcp",
|
||||
"headers": {
|
||||
"API_KEY": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Chat Stream
|
||||
|
||||
**POST /api/chat/stream**
|
||||
|
||||
```json
|
||||
{
|
||||
...
|
||||
"mcp_settings": {
|
||||
"servers": {
|
||||
"mcp-github-trending": {
|
||||
"transport": "stdio",
|
||||
"command": "uvx",
|
||||
"args": ["mcp-github-trending"],
|
||||
"env": {
|
||||
"MCP_SERVER_ID": "mcp-github-trending"
|
||||
},
|
||||
"enabled_tools": ["get_github_trending_repositories"],
|
||||
"add_to_agents": ["researcher"]
|
||||
}
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,740 @@
|
||||
{
|
||||
"openapi": "3.0.0",
|
||||
"info": {
|
||||
"title": "DeepFlow API",
|
||||
"description": "API for Deer - Advanced research and content generation system",
|
||||
"version": "0.1.0"
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "http://localhost:8000",
|
||||
"description": "Local development server"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/api/chat/stream": {
|
||||
"post": {
|
||||
"summary": "Stream chat responses",
|
||||
"description": "Initiates a streaming chat session with the research agent. Returns server-sent events with message chunks, tool calls, and intermediate results.",
|
||||
"tags": ["Chat"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ChatRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful streaming response",
|
||||
"content": {
|
||||
"text/event-stream": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"description": "Server-sent events with various message types"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "MCP server configuration is disabled"
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal server error during graph execution"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/tts": {
|
||||
"post": {
|
||||
"summary": "Convert text to speech",
|
||||
"description": "Converts text to speech using Volcengine TTS API. Requires VOLCENGINE_TTS_APPID and VOLCENGINE_TTS_ACCESS_TOKEN environment variables.",
|
||||
"tags": ["Text-to-Speech"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/TTSRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Audio file in requested format",
|
||||
"content": {
|
||||
"audio/mp3": {
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "binary"
|
||||
}
|
||||
},
|
||||
"audio/wav": {
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "binary"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Missing required environment variables"
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal server error during TTS processing"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/podcast/generate": {
|
||||
"post": {
|
||||
"summary": "Generate podcast from content",
|
||||
"description": "Generates an audio podcast from the provided text content",
|
||||
"tags": ["Content Generation"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/GeneratePodcastRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Generated podcast audio file",
|
||||
"content": {
|
||||
"audio/mp3": {
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "binary"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error during podcast generation"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/ppt/generate": {
|
||||
"post": {
|
||||
"summary": "Generate PowerPoint presentation",
|
||||
"description": "Generates a PowerPoint presentation from the provided content",
|
||||
"tags": ["Content Generation"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/GeneratePPTRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Generated PowerPoint file",
|
||||
"content": {
|
||||
"application/vnd.openxmlformats-officedocument.presentationml.presentation": {
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "binary"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error during PPT generation"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/prose/generate": {
|
||||
"post": {
|
||||
"summary": "Generate prose content",
|
||||
"description": "Generates prose content with streaming output based on the provided prompt and option",
|
||||
"tags": ["Content Generation"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/GenerateProseRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Streaming prose content",
|
||||
"content": {
|
||||
"text/event-stream": {
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"description": "Server-sent events with prose content chunks"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error during prose generation"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/prompt/enhance": {
|
||||
"post": {
|
||||
"summary": "Enhance user prompts",
|
||||
"description": "Enhances and refines user prompts with specified report style and context",
|
||||
"tags": ["Prompt"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/EnhancePromptRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Enhanced prompt result",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"result": {
|
||||
"type": "string",
|
||||
"description": "The enhanced prompt"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error during prompt enhancement"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/mcp/server/metadata": {
|
||||
"post": {
|
||||
"summary": "Get MCP server metadata",
|
||||
"description": "Retrieves metadata and available tools from a Model Context Protocol (MCP) server. Requires ENABLE_MCP_SERVER_CONFIGURATION=true.",
|
||||
"tags": ["MCP"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/MCPServerMetadataRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "MCP server metadata and available tools",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/MCPServerMetadataResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "MCP server configuration is disabled"
|
||||
},
|
||||
"500": {
|
||||
"description": "Error retrieving MCP server metadata"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/rag/config": {
|
||||
"get": {
|
||||
"summary": "Get RAG configuration",
|
||||
"description": "Returns the current RAG (Retrieval-Augmented Generation) provider configuration",
|
||||
"tags": ["RAG"],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "RAG configuration",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RAGConfigResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/rag/resources": {
|
||||
"get": {
|
||||
"summary": "Get RAG resources",
|
||||
"description": "Retrieves available resources from the RAG system based on optional query parameter",
|
||||
"tags": ["RAG"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "query",
|
||||
"in": "query",
|
||||
"description": "Search query for resources",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "List of RAG resources",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RAGResourcesResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/config": {
|
||||
"get": {
|
||||
"summary": "Get server configuration",
|
||||
"description": "Returns the complete server configuration including RAG settings and available models",
|
||||
"tags": ["Configuration"],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Server configuration",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ConfigResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"ChatRequest": {
|
||||
"type": "object",
|
||||
"description": "Request for chat streaming endpoint",
|
||||
"properties": {
|
||||
"messages": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/ChatMessage"
|
||||
},
|
||||
"description": "History of messages between the user and assistant"
|
||||
},
|
||||
"resources": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/Resource"
|
||||
},
|
||||
"description": "Resources to be used for the research"
|
||||
},
|
||||
"debug": {
|
||||
"type": "boolean",
|
||||
"default": false,
|
||||
"description": "Whether to enable debug logging"
|
||||
},
|
||||
"thread_id": {
|
||||
"type": "string",
|
||||
"default": "__default__",
|
||||
"description": "A specific conversation identifier"
|
||||
},
|
||||
"max_plan_iterations": {
|
||||
"type": "integer",
|
||||
"default": 1,
|
||||
"description": "The maximum number of plan iterations"
|
||||
},
|
||||
"max_step_num": {
|
||||
"type": "integer",
|
||||
"default": 3,
|
||||
"description": "The maximum number of steps in a plan"
|
||||
},
|
||||
"max_search_results": {
|
||||
"type": "integer",
|
||||
"default": 3,
|
||||
"description": "The maximum number of search results"
|
||||
},
|
||||
"auto_accepted_plan": {
|
||||
"type": "boolean",
|
||||
"default": false,
|
||||
"description": "Whether to automatically accept the plan"
|
||||
},
|
||||
"interrupt_feedback": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "Interrupt feedback from the user on the plan"
|
||||
},
|
||||
"mcp_settings": {
|
||||
"type": "object",
|
||||
"nullable": true,
|
||||
"description": "MCP settings for the chat request"
|
||||
},
|
||||
"enable_background_investigation": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Whether to get background investigation before plan"
|
||||
},
|
||||
"report_style": {
|
||||
"type": "string",
|
||||
"enum": ["ACADEMIC", "POPULAR_SCIENCE", "NEWS", "SOCIAL_MEDIA", "STRATEGIC_INVESTMENT"],
|
||||
"default": "ACADEMIC",
|
||||
"description": "The style of the report"
|
||||
},
|
||||
"enable_deep_thinking": {
|
||||
"type": "boolean",
|
||||
"default": false,
|
||||
"description": "Whether to enable deep thinking"
|
||||
},
|
||||
"enable_clarification": {
|
||||
"type": "boolean",
|
||||
"nullable": true,
|
||||
"description": "Whether to enable multi-turn clarification"
|
||||
},
|
||||
"max_clarification_rounds": {
|
||||
"type": "integer",
|
||||
"nullable": true,
|
||||
"description": "Maximum number of clarification rounds"
|
||||
}
|
||||
}
|
||||
},
|
||||
"ChatMessage": {
|
||||
"type": "object",
|
||||
"required": ["role", "content"],
|
||||
"properties": {
|
||||
"role": {
|
||||
"type": "string",
|
||||
"enum": ["user", "assistant"],
|
||||
"description": "The role of the message sender"
|
||||
},
|
||||
"content": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Text content"
|
||||
},
|
||||
{
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/ContentItem"
|
||||
},
|
||||
"description": "Multiple content items"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"ContentItem": {
|
||||
"type": "object",
|
||||
"required": ["type"],
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"description": "The type of content (text, image, etc.)"
|
||||
},
|
||||
"text": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The text content if type is 'text'"
|
||||
},
|
||||
"image_url": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The image URL if type is 'image'"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Resource": {
|
||||
"type": "object",
|
||||
"description": "A resource for RAG queries"
|
||||
},
|
||||
"TTSRequest": {
|
||||
"type": "object",
|
||||
"required": ["text"],
|
||||
"properties": {
|
||||
"text": {
|
||||
"type": "string",
|
||||
"description": "The text to convert to speech (max 1024 characters)"
|
||||
},
|
||||
"voice_type": {
|
||||
"type": "string",
|
||||
"default": "BV700_V2_streaming",
|
||||
"description": "The voice type to use"
|
||||
},
|
||||
"encoding": {
|
||||
"type": "string",
|
||||
"default": "mp3",
|
||||
"enum": ["mp3", "wav"],
|
||||
"description": "The audio encoding format"
|
||||
},
|
||||
"speed_ratio": {
|
||||
"type": "number",
|
||||
"format": "float",
|
||||
"default": 1.0,
|
||||
"description": "Speech speed ratio"
|
||||
},
|
||||
"volume_ratio": {
|
||||
"type": "number",
|
||||
"format": "float",
|
||||
"default": 1.0,
|
||||
"description": "Speech volume ratio"
|
||||
},
|
||||
"pitch_ratio": {
|
||||
"type": "number",
|
||||
"format": "float",
|
||||
"default": 1.0,
|
||||
"description": "Speech pitch ratio"
|
||||
},
|
||||
"text_type": {
|
||||
"type": "string",
|
||||
"default": "plain",
|
||||
"enum": ["plain", "ssml"],
|
||||
"description": "Text type"
|
||||
},
|
||||
"with_frontend": {
|
||||
"type": "integer",
|
||||
"default": 1,
|
||||
"description": "Whether to use frontend processing"
|
||||
},
|
||||
"frontend_type": {
|
||||
"type": "string",
|
||||
"default": "unitTson",
|
||||
"description": "Frontend type"
|
||||
}
|
||||
}
|
||||
},
|
||||
"GeneratePodcastRequest": {
|
||||
"type": "object",
|
||||
"required": ["content"],
|
||||
"properties": {
|
||||
"content": {
|
||||
"type": "string",
|
||||
"description": "The content of the podcast"
|
||||
}
|
||||
}
|
||||
},
|
||||
"GeneratePPTRequest": {
|
||||
"type": "object",
|
||||
"required": ["content"],
|
||||
"properties": {
|
||||
"content": {
|
||||
"type": "string",
|
||||
"description": "The content of the PowerPoint presentation"
|
||||
}
|
||||
}
|
||||
},
|
||||
"GenerateProseRequest": {
|
||||
"type": "object",
|
||||
"required": ["prompt", "option"],
|
||||
"properties": {
|
||||
"prompt": {
|
||||
"type": "string",
|
||||
"description": "The content/prompt of the prose"
|
||||
},
|
||||
"option": {
|
||||
"type": "string",
|
||||
"description": "The option of the prose writer"
|
||||
},
|
||||
"command": {
|
||||
"type": "string",
|
||||
"default": "",
|
||||
"description": "The user custom command of the prose writer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"EnhancePromptRequest": {
|
||||
"type": "object",
|
||||
"required": ["prompt"],
|
||||
"properties": {
|
||||
"prompt": {
|
||||
"type": "string",
|
||||
"description": "The original prompt to enhance"
|
||||
},
|
||||
"context": {
|
||||
"type": "string",
|
||||
"default": "",
|
||||
"description": "Additional context about the intended use"
|
||||
},
|
||||
"report_style": {
|
||||
"type": "string",
|
||||
"default": "academic",
|
||||
"enum": ["academic", "ACADEMIC", "popular_science", "POPULAR_SCIENCE", "news", "NEWS", "social_media", "SOCIAL_MEDIA", "strategic_investment", "STRATEGIC_INVESTMENT"],
|
||||
"description": "The style of the report"
|
||||
}
|
||||
}
|
||||
},
|
||||
"MCPServerMetadataRequest": {
|
||||
"type": "object",
|
||||
"required": ["transport"],
|
||||
"properties": {
|
||||
"transport": {
|
||||
"type": "string",
|
||||
"enum": ["stdio", "sse", "streamable_http"],
|
||||
"description": "The type of MCP server connection"
|
||||
},
|
||||
"command": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The command to execute (for stdio type)"
|
||||
},
|
||||
"args": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"nullable": true,
|
||||
"description": "Command arguments (for stdio type)"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The URL of the SSE server (for sse type)"
|
||||
},
|
||||
"env": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "string"
|
||||
},
|
||||
"nullable": true,
|
||||
"description": "Environment variables (for stdio type)"
|
||||
},
|
||||
"headers": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "string"
|
||||
},
|
||||
"nullable": true,
|
||||
"description": "HTTP headers (for sse/streamable_http type)"
|
||||
},
|
||||
"timeout_seconds": {
|
||||
"type": "integer",
|
||||
"nullable": true,
|
||||
"description": "Optional custom timeout in seconds"
|
||||
}
|
||||
}
|
||||
},
|
||||
"MCPServerMetadataResponse": {
|
||||
"type": "object",
|
||||
"required": ["transport"],
|
||||
"properties": {
|
||||
"transport": {
|
||||
"type": "string",
|
||||
"description": "The type of MCP server connection"
|
||||
},
|
||||
"command": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The command to execute (for stdio type)"
|
||||
},
|
||||
"args": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"nullable": true,
|
||||
"description": "Command arguments (for stdio type)"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The URL of the SSE server (for sse type)"
|
||||
},
|
||||
"env": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "string"
|
||||
},
|
||||
"nullable": true,
|
||||
"description": "Environment variables (for stdio type)"
|
||||
},
|
||||
"headers": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "string"
|
||||
},
|
||||
"nullable": true,
|
||||
"description": "HTTP headers (for sse/streamable_http type)"
|
||||
},
|
||||
"tools": {
|
||||
"type": "array",
|
||||
"description": "Available tools from the MCP server"
|
||||
}
|
||||
}
|
||||
},
|
||||
"RAGConfigResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"provider": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The provider of the RAG (default: ragflow)"
|
||||
}
|
||||
}
|
||||
},
|
||||
"RAGResourceRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "The query of the resource to be searched"
|
||||
}
|
||||
}
|
||||
},
|
||||
"RAGResourcesResponse": {
|
||||
"type": "object",
|
||||
"required": ["resources"],
|
||||
"properties": {
|
||||
"resources": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/Resource"
|
||||
},
|
||||
"description": "The resources of the RAG"
|
||||
}
|
||||
}
|
||||
},
|
||||
"ConfigResponse": {
|
||||
"type": "object",
|
||||
"required": ["rag", "models"],
|
||||
"properties": {
|
||||
"rag": {
|
||||
"$ref": "#/components/schemas/RAGConfigResponse",
|
||||
"description": "The config of the RAG"
|
||||
},
|
||||
"models": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": "The configured models"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user