vitepress-template

Appearance

Specialized Services ​

**Referenced Files in This Document** - [[README.md]](file/readme.md) - [[bi-chat/docs/chat_v1_design.md]](file/bi-chat/docs/chat-v1-design.md) - [[bi-chat/bi_chat/main.py]](file/bi-chat/bi-chat/main.py) - [[bi-chat-asktable/app/main.py]](file/bi-chat-asktable/app/main.py) - [[bi-notify/cmd/bi-notify/main.go]](file/bi-notify/cmd/bi-notify/main.go) - [[bi-plan-taoxi/cmd/bi-plan-taoxi/main.go]](file/bi-plan-taoxi/cmd/bi-plan-taoxi/main.go) - [[bi-api-leke/README.md]](file/bi-api-leke/readme.md) - [[bi-api-leke/cmd/bi-api-leke/main.go]](file/bi-api-leke/cmd/bi-api-leke/main.go) - [[bi-api-jushuitan/cmd/bi-api-jushuitan/main.go]](file/bi-api-jushuitan/cmd/bi-api-jushuitan/main.go)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document explains five specialized backend services that power domain-specific capabilities in the BI platform:

  • Bi-chat AI multi-agent system with conversation management and agent coordination
  • Bi-chat-asktable NL2SQL integration
  • Bi-notify notification system with multi-channel delivery
  • Bi-plan-taoxi Taobao advertising management
  • Data synchronization services bi-api-leke and bi-api-jushuitan

Each service is designed for high reliability, scalability, and operational simplicity, integrating with shared infrastructure such as configuration via Nacos, observability, and messaging via Kafka.

Project Structure ​

The repository organizes services by domain and technology. The specialized services are located under dedicated directories, each with its own Kratos or FastAPI entrypoint, configuration, and domain-specific modules.

Diagram sources

Section sources

Core Components ​

  • Bi-chat AI multi-agent system: Provides conversational AI with session management, memory (short-term and long-term), and tooling for SQL execution and entity search.
  • Bi-chat-asktable NL2SQL integration: Bridges natural language queries to SQL via AskTable, with row-level access control and Nacos-driven configuration.
  • Bi-notify notification system: Centralized notifications with multi-channel delivery and Kafka-backed asynchronous processing.
  • Bi-plan-taoxi Taobao advertising management: Kratos-based service for managing Taobao ad plans and campaigns.
  • Bi-api-leke and bi-api-jushuitan: Data synchronization services for Taobao ecosystem APIs (Leke and JuShuiTan), leveraging Kafka for asynchronous ingestion.

Section sources

Architecture Overview ​

The specialized services share common infrastructure:

  • Configuration via Nacos
  • Observability and logging
  • Messaging via Kafka for asynchronous workflows
  • Kratos or FastAPI for transport

Diagram sources

Detailed Component Analysis ​

Bi-chat AI Multi-Agent System ​

Purpose:

  • Enable conversational analytics with ReAct-style reasoning, tool use, and persistent memory across sessions.
  • Coordinate agent lifecycles, manage concurrency, and deliver streaming responses.

Key features:

  • Conversation lifecycle management with LRU cache and idle cleanup
  • Dual memory: short-term (session) and long-term (user-level) with vector storage
  • Tooling for entity search, indicator lookup, SQL execution, and environment perception
  • Streaming output compatible with SSE/OpenAI chunk format

Diagram sources

Section sources

Bi-chat-AskTable NL2SQL Integration ​

Purpose:

  • Convert natural language questions into executable SQL via AskTable with row-level access control.
  • Provide a configurable FastAPI service with Nacos-driven settings.

Integration pattern:

  • Load configuration from Nacos at startup
  • Expose routes for NL2SQL translation
  • Enforce row-level access control before returning results

Diagram sources

Section sources

Bi-notify Notification System ​

Purpose:

  • Centralized notification delivery with multi-channel support and asynchronous processing via Kafka.

Integration pattern:

  • Kratos-based service with HTTP/gRPC servers
  • Startup initializes and starts Kafka consumer groups for notification topics
  • Graceful shutdown ensures consumers are stopped

Diagram sources

Section sources

Bi-plan-taoxi Taobao Advertising Management ​

Purpose:

  • Manage Taobao advertising plans and campaigns via a Kratos service with Nacos configuration.

Integration pattern:

  • Environment-aware configuration loading
  • Kratos server lifecycle management
  • Shared logging and observability

Diagram sources

Section sources

Bi-api-Leke Data Synchronization ​

Purpose:

  • Synchronize Taobao merchant data (orders, items, refunds) into the platform using Kafka for asynchronous processing.

Key features:

  • Services: Shop, Goods, Orders
  • Kafka consumers for full/incremental order sync, refunds, and items-onsale sync
  • Nacos configuration for runtime settings

Diagram sources

Section sources

Bi-api-Jushuitan Data Synchronization ​

Purpose:

  • Synchronize inventory, purchase, inbound/outbound, and other operational data from Jushuitan via Kafka.

Integration pattern:

  • Kratos service with Nacos config and Snowflake ID initialization
  • Kafka producers/consumers orchestrated via ConsumerManager

Diagram sources

Section sources

Dependency Analysis ​

  • Configuration: All Kratos services load configuration from Nacos and initialize logging/observability.
  • Messaging: Kafka is used for asynchronous workflows across bi-chat (streaming), bi-notify (consumers), bi-api-leke, and bi-api-jushuitan (producers/consumers).
  • Transport: Kratos manages HTTP/gRPC servers; FastAPI manages HTTP for bi-chat-asktable.
  • Shared libraries: bi-common provides Nacos, Kafka, Redis, GORM, and logging utilities.

Diagram sources

Section sources

Performance Considerations ​

  • Concurrency and resource sharing:
    • Bi-chat: LRU session cache with periodic cleanup; shared model and embedding instances reduce cold-start overhead.
    • Bi-notify: Consumer groups and worker counts configured per topic to balance throughput.
    • Data sync services: Worker pools and partitioned topics improve parallelism.
  • Streaming and memory:
    • Bi-chat streaming minimizes payload duplication and supports incremental text deltas.
    • Memory compression thresholds prevent excessive memory usage in long sessions.
  • Observability:
    • Structured logs and OpenTelemetry integration aid in latency and error tracking.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • Configuration not loading:
    • Verify Nacos endpoint and Data ID for each service’s application YAML.
    • Confirm environment flag (-env) matches the intended config file.
  • Kafka connectivity:
    • Check broker addresses and consumer group IDs in configuration.
    • Ensure topics exist and permissions are granted.
  • Session cleanup issues:
    • Bi-chat periodically cleans idle sessions; confirm scheduled task runs and logs.
  • Snowflake ID initialization:
    • For bi-api-jushuitan, ensure Snowflake settings are present in Nacos and service can fetch naming client.

Section sources

Conclusion ​

These specialized services form the backbone of the BI platform’s AI-driven conversations, data synchronization, and operational workflows. They leverage shared infrastructure for configuration, observability, and messaging to achieve reliability and scalability. Each service adheres to consistent patterns—Nacos-based configuration, Kratos/FastAPI transport, and Kafka-driven asynchronous processing—while delivering domain-specific value.

[No sources needed since this section summarizes without analyzing specific files]