Update project and configurations
This commit is contained in:
Zou-Seay
161
intelligent_cabin/README.md
Normal file
161
intelligent_cabin/README.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Intelligent Cabin Agent
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Create and activate the Python 3.11 virtual environment:
|
||||
|
||||
```bash
|
||||
uv venv .venv --python 3.11
|
||||
source .venv/bin/activate
|
||||
```
|
||||
2. Install dependencies:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. Start the service:
|
||||
|
||||
```bash
|
||||
.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||||
```
|
||||
|
||||
4. Open the API docs:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:8000/docs
|
||||
```
|
||||
|
||||
Demo UI:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:8000/demo
|
||||
```
|
||||
|
||||
Architecture and flow review:
|
||||
|
||||
```text
|
||||
solution_review.md
|
||||
```
|
||||
|
||||
The demo console supports:
|
||||
|
||||
- local browser session history restore
|
||||
- runtime matcher/classifier/session backend switching
|
||||
- matcher routing debug panel with Top-K candidates
|
||||
- local `rewrite -> keyword/classifier/retrieval -> fusion` decision trace
|
||||
- direct display of classifier backend / raw label / fallback reason / raw candidate payload
|
||||
- workflow JSON visualization
|
||||
|
||||
## Core APIs
|
||||
|
||||
- `POST /api/v1/agent/chat`
|
||||
- `POST /api/v1/agent/fill-slots`
|
||||
- `GET /health`
|
||||
|
||||
## Current Scope
|
||||
|
||||
- Configurable session backend: memory / Redis
|
||||
- Config-driven intent registry
|
||||
- Router layer with pluggable matcher / extractor
|
||||
- Rule-based fast-path intent routing
|
||||
- Basic slot extraction
|
||||
- Plugin registry with mock handlers
|
||||
- Workflow response payloads
|
||||
|
||||
## Runtime Config
|
||||
|
||||
- `AGENT_SESSION_BACKEND=memory|redis`
|
||||
- `AGENT_REDIS_URL=redis://127.0.0.1:6379/0`
|
||||
- `AGENT_REDIS_KEY_PREFIX=agent:session`
|
||||
- `AGENT_SESSION_TTL_SECONDS=86400`
|
||||
- `AGENT_MATCHER_PIPELINE=keyword`
|
||||
- `AGENT_SLOT_EXTRACTOR_BACKEND=heuristic`
|
||||
- `AGENT_CLASSIFIER_BACKEND=mock`
|
||||
- `AGENT_CLASSIFIER_THRESHOLD=1.2`
|
||||
- `AGENT_CLASSIFIER_BERT_THRESHOLD=0.0`
|
||||
- `AGENT_CLASSIFIER_MODEL_PATH=/path/to/model`
|
||||
- `AGENT_CLASSIFIER_LABEL_MAP_PATH=/path/to/label_map.json`
|
||||
- `AGENT_CLASSIFIER_REMOTE_URL=http://127.0.0.1:9000/classify`
|
||||
- `AGENT_CLASSIFIER_REMOTE_TIMEOUT_SECONDS=3.0`
|
||||
- `AGENT_LOCAL_EXECUTE_THRESHOLD=1.65`
|
||||
- `AGENT_LOCAL_ROUTE_TO_CLOUD_THRESHOLD=0.75`
|
||||
- `AGENT_LOCAL_CLARIFY_MARGIN_THRESHOLD=0.12`
|
||||
- `AGENT_PLANNER_BACKEND=heuristic|dashscope`
|
||||
- `AGENT_PLANNER_BASE_URL=https://your-base-url/v1`
|
||||
- `AGENT_PLANNER_API_KEY=your-api-key`
|
||||
- `AGENT_PLANNER_MODEL_NAME=qwen3.5-plus`
|
||||
- `AGENT_PLANNER_TIMEOUT_SECONDS=6.0`
|
||||
|
||||
Matcher pipeline examples:
|
||||
|
||||
- `AGENT_MATCHER_PIPELINE=keyword`
|
||||
- `AGENT_MATCHER_PIPELINE=keyword,classifier,retrieval`
|
||||
- `AGENT_MATCHER_PIPELINE=keyword,retrieval`
|
||||
- `AGENT_MATCHER_PIPELINE=classifier`
|
||||
- `AGENT_MATCHER_PIPELINE=retrieval`
|
||||
|
||||
Classifier backend examples:
|
||||
|
||||
- `AGENT_CLASSIFIER_BACKEND=mock`
|
||||
- `AGENT_CLASSIFIER_BACKEND=bert`
|
||||
- `AGENT_CLASSIFIER_BACKEND=remote`
|
||||
- `AGENT_CLASSIFIER_TOP_K=3`
|
||||
|
||||
For local BERT models:
|
||||
|
||||
- install optional runtime deps such as `transformers` and a backend like `torch`
|
||||
- point `AGENT_CLASSIFIER_MODEL_PATH` to the local model directory
|
||||
- if the model outputs labels like `LABEL_0`, provide `AGENT_CLASSIFIER_LABEL_MAP_PATH`
|
||||
- use `AGENT_CLASSIFIER_BERT_THRESHOLD` instead of the mock threshold
|
||||
|
||||
Example label map:
|
||||
|
||||
```json
|
||||
{
|
||||
"LABEL_0": "cs_query_order",
|
||||
"LABEL_1": "cs_cancel_order",
|
||||
"LABEL_2": "cabin_play_music"
|
||||
}
|
||||
```
|
||||
|
||||
Remote classifier expected request payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "我的订单现在什么情况 A808001",
|
||||
"top_k": 3,
|
||||
"labels": ["cs_query_order", "cs_cancel_order", "cabin_play_music"]
|
||||
}
|
||||
```
|
||||
|
||||
Remote classifier response payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"intent_id": "cs_query_order",
|
||||
"label": "LABEL_0",
|
||||
"score": 0.982,
|
||||
"model_name": "bert-remote-v1",
|
||||
"candidates": [
|
||||
{"label": "LABEL_0", "intent_id": "cs_query_order", "score": 0.982},
|
||||
{"label": "LABEL_1", "intent_id": "cs_cancel_order", "score": 0.011},
|
||||
{"label": "LABEL_7", "intent_id": "cs_query_logistics", "score": 0.007}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When `bert` or `remote` is unavailable or below threshold, the classifier falls back to `mock`, and the demo debug panel shows both the attempted backend and the fallback reason.
|
||||
|
||||
Planner notes:
|
||||
|
||||
- keep the planner key in environment variables, not in source code or front-end code
|
||||
- the planner uses `POST {base_url}/chat/completions`
|
||||
- for DashScope OpenAI-compatible endpoints, use the compatible `v1` base URL and set `AGENT_PLANNER_BACKEND=dashscope`
|
||||
- when cloud planning is unavailable, the service falls back to a local heuristic planner for multi-command splitting
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Replace rule router with classifier + retrieval + LLM
|
||||
- Connect real business plugins
|
||||
- Add automated tests
|
||||
Reference in New Issue
Block a user