# AI开发框架

**Repository Path**: lobyliang/aiframework

## Basic Information

- **Project Name**: AI开发框架
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Framework — Multi-Agent AI Service

A production-grade multi-agent AI service framework built with **FastAPI** and **LangGraph**, featuring RAG (Retrieval-Augmented Generation), voice AI (ASR/TTS/VAD), MCP tool integration, and SSE streaming.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                     FastAPI Server                       │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐         │
│  │Health│ │ Files│ │Agents│ │ Chat │ │ Voice│         │
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘         │
│                        │                                │
│  ┌─────────────────────┼──────────────────────────┐    │
│  │          Agent Service / Graph Manager         │    │
│  │  ┌──────────────────┴──────────────────┐      │    │
│  │  │      LangGraph Agent Graphs         │      │    │
│  │  │  ┌──────────┐  ┌────────────────┐   │      │    │
│  │  │  │ Calendar │  │ MaterialSearch │   │      │    │
│  │  │  │  Agent   │  │    Agent       │   │      │    │
│  │  │  └──────────┘  └────────────────┘   │      │    │
│  │  └─────────────────────────────────────┘      │    │
│  └───────────────────────────────────────────────┘    │
│                        │                                │
│  ┌─────────────────────┼──────────────────────────┐    │
│  │   RAG / Vector DB   │    Voice Providers       │    │
│  │  (Weaviate/Qdrant)  │  (ASR · TTS · VAD)      │    │
│  └─────────────────────┘                          │    │
│  ┌─────────────────────┐  ┌───────────────────┐   │    │
│  │   MCP Tool Adapters │  │  File / Storage   │   │    │
│  │  (ArXiv·12306·MCP)  │  │  (OpendAL·Local)  │   │    │
│  └─────────────────────┘  └───────────────────┘   │    │
└─────────────────────────────────────────────────────────┘
```

## Features

- **Multi-Agent Graph Engine** — LangGraph-based agent graphs with configurable nodes (RAG retrieval, LLM response, tool execution)
- **RAG (Retrieval-Augmented Generation)** — Multi-index vector search (Weaviate / Qdrant) & Dify knowledge base integration
- **SSE Streaming** — Real-time server-sent events for chat and voice transcription
- **Voice AI** — Modular ASR, TTS, VAD providers with streaming audio support
- **MCP Integration** — Model Context Protocol adapters (ArXiv, 12306, custom MCP servers)
- **File Management** — Upload/download with deduplication (MD5), TTL-based auto-cleanup, multi-backend storage (OpendAL/local)
- **Conversation Management** — Session-based chat history with PostgreSQL persistence
- **Authentication & Middleware** — CORS, request logging, optional auth middleware
- **Dockerized** — Multi-stage Dockerfile + docker-compose with PostgreSQL, Redis, Weaviate/Qdrant

## Quick Start

### Prerequisites

- Python 3.11+
- PostgreSQL 15+
- Redis 7+
- (Optional) Weaviate or Qdrant for vector search

### Local Development

```bash
# Clone and setup
git clone <repo> && cd ai_framwork
python -m venv .venv && source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Configure environment
cp docker/.env.example .env
# Edit .env with your DB/Redis/LLM settings

# Run database migrations
alembic upgrade head

# Start the server
python main.py
```

### Docker Deployment

```bash
docker compose up -d
# Or with Qdrant:
docker compose --profile qdrant up -d
```

## Configuration

All settings are managed via environment variables using `pydantic-settings`:

| Config | File | Key Variables |
|--------|------|--------------|
| App | `config/app.py` | `HOST`, `PORT`, `WS_HOST`, `REDIS_*`, `LOG_LEVEL` |
| Database | `config/db.py` | `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` |
| LLM | `config/llm.py` | `LLM_PROVIDER`, `LLM_API_KEY`, `LLM_MODEL`, `ASR_*`, `TTS_*` |
| RAG | `config/rag.py` | `EMBEDDING_DB_TYPE`, `DIFY_API_BASE_URL`, `DIFY_DATASET_IDS` |

## API Endpoints

| Route | Description |
|-------|------------|
| `GET /health` | Health check |
| `GET /v1/agents` | List all registered agents |
| `GET /v1/agents/{uuid}` | Get agent details |
| `GET /v1/agents/{uuid}/conversations` | List conversations for a user |
| `POST /v1/chat` | Chat with default agent (SSE) |
| `POST /v1/agents/{uuid}/chat` | Chat with specific agent (SSE) |
| `POST /v1/files/upload` | Upload a file |
| `GET /v1/files/{id}` | Download a file |
| `DELETE /v1/files/{id}` | Delete a file |
| `POST /v1/voice/transcribe` | Streaming ASR transcription (SSE) |
| `POST /v1/voice/synthesize` | Text-to-speech synthesis |

Interactive API docs at `/docs` (Swagger) or `/redoc`.

## Agents

Agents are LangGraph-based state machines composed of reusable nodes:

| Agent | Description | Graph |
|-------|------------|-------|
| **Calendar Agent** | Dify RAG + weather MCP + calendar tools | `START → retrieve_rag → generate_response → execute_tools` |
| **Material Search Agent** | Qdrant multi-index RAG + search tools | `START → search_rag → generate_response → execute_tools` |

### Creating a New Agent

```python
from ai_framwork.agents.base.base_agent import BaseAgent
from langgraph.graph import StateGraph, START, END

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(name="my_agent", description="Does something useful")

    async def initialize(self):
        pass

    def create_graph(self, saver, store):
        builder = StateGraph(AgentState)
        builder.add_node("node_name", my_node_function)
        builder.add_edge(START, "node_name")
        builder.add_edge("node_name", END)
        return builder.compile(checkpointer=saver, store=store)
```

## Project Structure

```
ai_framwork/
├── ai_framwork/           # Application core
│   ├── api/               # FastAPI routes, middleware, models
│   ├── agents/            # Agent system
│   │   ├── base/          # Abstract agent base class
│   │   ├── graphs/        # LangGraph agent implementations
│   │   │   └── nodes/     # Reusable graph nodes (RAG, LLM, tools)
│   │   ├── manager/       # Agent lifecycle, session management
│   │   ├── mcps/          # MCP tool adapters (ArXiv, 12306, etc.)
│   │   ├── models/        # LLM adapter & capability registry
│   │   └── prompts/       # System prompts
│   ├── core/              # Runtime, RAG services
│   ├── adapters/          # LLM stream adapters
│   ├── providers/         # Voice providers (ASR, TTS, VAD)
│   ├── tools/             # Built-in tools
│   ├── data_models/       # Pydantic models
│   └── entities/          # Domain entities & API forms
├── config/                # Pydantic settings
├── models/                # SQLAlchemy ORM models
├── entities/              # Shared entities
├── libs/                  # Utilities (doc parsing, URL signing)
├── soa/                   # Service-oriented architecture layer
│   ├── cache/             # Redis caching
│   ├── mqtt/              # MQTT messaging
│   └── storage/           # File storage backend
├── service/               # External service interfaces
├── docker/                # Docker Compose & env example
├── migrations/            # Alembic DB migrations
└── tests/                 # Test suite
```

## Testing

```bash
# Run all tests
pytest

# With coverage
pytest --cov=ai_framwork

# Watch mode
pytest --looponfail
```

## Tech Stack

| Component | Technology |
|-----------|-----------|
| **Runtime** | Python 3.11, FastAPI, Uvicorn |
| **Agent Framework** | LangGraph, LangChain |
| **LLM** | DashScope (Qwen), custom adapters |
| **Database** | PostgreSQL (async via SQLAlchemy + asyncpg) |
| **Cache** | Redis |
| **Vector DB** | Weaviate / Qdrant |
| **RAG** | Dify API, custom multi-index search |
| **Voice** | Modular ASR/TTS/VAD providers |
| **Tool Integration** | MCP (Model Context Protocol) |
| **Storage** | OpendAL, local filesystem |
| **Messaging** | MQTT |
| **Deployment** | Docker, docker-compose |