开源AI工作流

Prerequisites

• Python 3.11 or higher
• Access to a supported LLM provider (OpenAI, Anthropic, etc.)
• Data Warehouse (Database) credentials (like Presto, PostgreSQL, MySQL, etc.)
• (Optional) Embedding model for vector-based retrieval - if not available, BM25-based retrieval will be used
• (Optional) Docker - required only for docker executor mode

Note on Chinese Text Segmentation: For better Chinese text retrieval, jieba is used for word segmentation. However, jieba is not compatible with Python 3.12+. On Python 3.12 and higher, the system automatically falls back to simple punctuation-based segmentation for Chinese text.

Getting started

Installation & Setup

Installation

1. Using uv (recommended):

git clone git@github.com:zhongyu09/openchatbi
uv sync

1. Using pip:

pip install openchatbi

1. For development:

git clone git@github.com:zhongyu09/openchatbi
uv sync --group dev

Optional: If you want to use pysqlite3 (newer SQLite builds), you can install it manually. If build fails, install SQLite first:

On macOS, try to install sqlite using Homebrew:

brew install sqlite
brew info sqlite
export LDFLAGS="-L/opt/homebrew/opt/sqlite/lib"
export CPPFLAGS="-I/opt/homebrew/opt/sqlite/include"

sudo yum install sqlite-devel

sudo apt-get update
sudo apt-get install libsqlite3-dev

Time Series Forecasting Service Setup

OpenChatBI can integrate with a time series forecasting service for advanced predictive analytics. Follow these steps to set up the service:

1. Build and Run the Forecasting Service

See detailed instructions in timeseries_forecasting/README.md

Quick start:

cd timeseries_forecasting
./build_and_run.sh

2. Configure Tool Usage Rules

In your bi.yaml, add constraints for the timeseries_forecast tool, e.g. if you are using timer-base-84m model:

extra_tool_use_rule: |
  - timeseries_forecast tool requires at least 96 time points in input data. If no enough input data, set input_len to 96 to pad with zeros.

3. Configure Service URL

In your config.yaml: ```yaml

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request

Run Demo

Run demo using example dataset from spider dataset. You need to provide "YOUR OPENAI API KEY" or change config to use other LLM providers.

Note: The demo example includes embedding model configuration. If you want to run without an embedding model, you can remove the embedding_model section in the config - BM25 retrieval will be used automatically.

cp example/config.yaml openchatbi/config.yaml
sed -i 's/YOUR_API_KEY_HERE/[YOUR OPENAI API KEY]/g' openchatbi/config.yaml
python run_streamlit_ui.py

Configuration

1. Create configuration file

Copy the configuration template:

cp openchatbi/config.yaml.template openchatbi/config.yaml

1. Configure your LLMs:

```yaml

Configuration Instructions

The configuration template is provided at config.yaml.template. Key configuration sections include:

Basic Settings

• organization: Organization name (e.g., "Your Company")
• dialect: Database dialect (e.g., "presto")
• bi_config_file: Path to BI configuration file (e.g., "example/bi.yaml")

Catalog Store Configuration

• catalog_store: Configuration for data catalog storage
• store_type: Storage type (e.g., "file_system")
• data_path: Path to catalog data stored by file system (e.g., "./example")

Data Warehouse Configuration

• data_warehouse_config: Database connection settings
• uri: Connection string for your database
• include_tables: List of tables to include in catalog, leave empty to include all tables
• database_name: Database name for catalog
• token_service: Token service URL (for data warehouse that need token authentication like Presto)
• user_name / password: Token service credentials

LLM Configuration

Various LLMs are supported based on LangChain, see LangChain API Document(https://python.langchain.com/api_reference/reference.html#integrations) for full list that support chat_models. You can configure different LLMs for different tasks:

• default_llm: Primary language model for general tasks
• embedding_model: (Optional) Model for embedding generation. If not configured, BM25-based text retrieval will be used as fallback, and the memory tools will not work
• text2sql_llm: (Optional) Specialized model for SQL generation. If not configured, uses default_llm

Multiple providers (optional):

• Configure multiple providers under llm_providers and select with default_llm: <provider_name>.
• In sample_ui/streamlit_ui.py, a provider dropdown appears when llm_providers is configured.
• In sample_api/async_api.py, pass provider in the /chat/stream request body.

Commonly used LLM providers and their corresponding classes and installation commands:

• Anthropic: langchain_anthropic.ChatAnthropic, pip install langchain-anthropic
• OpenAI: langchain_openai.ChatOpenAI, pip install langchain-openai
• Azure OpenAI: langchain_openai.AzureChatOpenAI, pip install langchain-openai
• Google Vertex AI: langchain_google_vertexai.ChatVertexAI, pip install langchain-google-vertexai
• Bedrock: langchain_aws.ChatBedrock, pip install langchain-aws
• Huggingface: langchain_huggingface.ChatHuggingFace, pip install langchain-huggingface
• Deepseek: langchain_deepseek.ChatDeepSeek, pip install langchain-deepseek
• Ollama: langchain_ollama.ChatOllama, pip install langchain-ollama

Advanced Configuration

OpenChatBI supports sophisticated customization through prompt engineering and catalog management features:

• Prompt Engineering Configuration: Customize system prompts, business glossaries, and data warehouse introductions
• Data Catalog Management: Configure table metadata, column descriptions, and SQL generation rules
• Business Rules: Define table selection criteria and domain-specific SQL constraints
• Forecasting Service: Configure the forecasting service url and prompt based on your own deployment

For detailed configuration options and examples, see the Advanced Features section.

Visualization configuration

You can choose rule-based or llm-based visualization or disable visualization. ```yaml

Options: "rule" (rule-based), "llm" (LLM-based), or null (skip visualization)

visualization_mode: llm ```

Time Series Forecasting Service Configuration

timeseries_forecasting_service_url: "http://localhost:8765"

**Important**: Adjust the URL based on your deployment scenario:
- **Local development** (OpenChatBI on host, Forecasting service in Docker): `http://localhost:8765`
- **Remote service**: `http://your-service-host:8765`


#### 4. Verify Service Health

Test the service is accessible:

Expected response:

Python Code Execution Configuration

OpenChatBI supports multiple execution environments for running Python code with different security and performance characteristics:

```yaml

Python Code Execution Configuration

python_executor: local # Options: "local", "restricted_local", "docker" ```

Executor Types

• local (Default)
• Performance: Fastest execution
• Security: Least secure (code runs in current Python process)
• Capabilities: Full Python capabilities and library access
• Use Case: Development environments, trusted code execution

• restricted_local
• Performance: Moderate execution speed
• Security: Moderate security with RestrictedPython sandboxing
• Capabilities: Limited Python features (no imports, file access, etc.)
• Use Case: Semi-trusted environments with controlled execution

• docker
• Performance: Slower due to container overhead
• Security: Highest security with complete process isolation
• Capabilities: Full Python capabilities within isolated container
• Use Case: Production environments, untrusted code execution
• Requirements: Docker must be installed and running

Docker Executor Setup

For production deployments or when running untrusted code, the Docker executor provides complete isolation:

1. Install Docker: Download and install Docker Desktop or Docker Engine
2. Configure executor: Set python_executor: docker in your config
3. Automatic setup: OpenChatBI will automatically build the required Docker image
4. Fallback behavior: If Docker is unavailable, automatically falls back to local executor

Docker Executor Features: - Pre-installed data science libraries (pandas, numpy, matplotlib, seaborn) - Network isolation for security - Automatic container cleanup - Resource isolation from host system