# CSM-LLM-QA

**Repository Path**: NEVSTOP-LAB/CSM-LLM-QA

## Basic Information

- **Project Name**: CSM-LLM-QA
- **Description**: 通过 LLM+RAG 实现回复CSM相关问题的基础设施
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-01
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSM-LLM-QA

> 通用 RAG 问答 Python 库 —— 基于 CSM Wiki / LabVIEW 知识库，封装 LLM 调用与向量检索，对外仅暴露一个简洁的 `CSM_QA` 类。

---

## 安装

```bash
pip install csm-llm-qa
```

依赖：`openai>=1.0`、`chromadb>=0.4`、`sentence-transformers>=2.2`、`charset-normalizer>=3.0`。

---

## 60 秒上手

```python
from csm_llm_qa import CSM_QA

qa = CSM_QA(api_key="sk-deepseek-xxx")           # 默认 provider=deepseek
answer = qa.ask("CSM 框架中的状态机如何切换？")
print(answer)
```

带历史对话：

```python
from csm_llm_qa import CSM_QA, Message

qa = CSM_QA(api_key="sk-xxx")
history = [
    Message(role="user", content="CSM 是什么？"),
    Message(role="assistant", content="CSM 是 Communicable State Machine ..."),
]
answer = qa.ask("那它和 JKI SM 的区别？", history=history)
```

需要更多元信息？

```python
result = qa.ask_detailed("CSM 状态机如何切换？", history=history)
print(result.answer)         # 文本
print(result.contexts)       # 命中的 RAG 片段
print(result.usage)          # token 用量
print(result.prompt_messages)  # 实际发往 LLM 的 messages（调试用）
```

---

## API 参数

```python
CSM_QA(
    api_key,                                # 必填
    *,
    provider="deepseek",                    # "deepseek" 或 "openai_compatible"
    model=None,                             # None → 取 provider 默认
    base_url=None,                          # None → 取 provider 默认
    temperature=0.5,
    max_tokens=2048,
    max_retries=3,
    request_timeout=60.0,

    wiki_dir="csm-wiki/remote",             # 知识库目录
    vector_store_dir=".csm_llm_qa/vector_store",
    embedding_provider="local",             # "local"（本地）或 "openai"
    embedding_model="BAAI/bge-small-zh-v1.5",
    embedding_api_key=None,
    embedding_base_url=None,
    top_k=6,
    similarity_threshold=0.72,

    system_prompt=None,                     # None → 内置 CSM/LabVIEW prompt
    wiki_base_url="https://github.com/NEVSTOP-LAB/CSM-Wiki/blob/main",  # 关键信息回答时的链接前缀
    auto_sync_wiki=True,                    # 首次运行若向量库为空，自动同步
)
```

### 支持的 LLM 供应商

| `provider`            | 默认 `base_url`                    | 默认 `model`     | 备注                              |
| --------------------- | ---------------------------------- | ---------------- | --------------------------------- |
| `deepseek`            | `https://api.deepseek.com`         | `deepseek-chat`  | DeepSeek 官方                      |
| `openai_compatible`   | 必须传                             | 必须传           | OpenAI 官方、Moonshot、智谱、本地 vLLM/Ollama 等任意 OpenAI 兼容服务 |

示例：使用 OpenAI 官方

```python
qa = CSM_QA(
    api_key="sk-xxx",
    provider="openai_compatible",
    base_url="https://api.openai.com/v1",
    model="gpt-4o-mini",
)
```

### 从环境变量构造

```python
qa = CSM_QA.from_env()
# 识别的环境变量（统一以 LLM_* 前缀，无别名）：
# LLM_API_KEY / LLM_PROVIDER / LLM_MODEL / LLM_BASE_URL
```

### 从 INI 配置文件构造

```python
qa = CSM_QA.from_ini("config.ini")
# 支持相对路径和绝对路径；可用参数覆盖文件配置：
# qa = CSM_QA.from_ini("config.ini", api_key="sk-override")
```

示例配置见 [`examples/config.ini.example`](examples/config.ini.example)。

---

## 知识库

把任意 Markdown 文档放入 `csm-wiki/remote/` 目录即可（支持子目录、UTF-8 / GBK / Big5 自动识别）。

- 首次构造 `CSM_QA` 时若向量库为空：
  - 若 `csm-wiki/remote/` 目录不存在但 `csm-wiki/wiki_source.json` 存在，会自动从远程仓库克隆 wiki 并建立索引。
  - 若 `csm-wiki/remote/` 已存在，则直接对目录做增量同步。
  - 若两者均不存在，则跳过同步（无 RAG 上下文，仅凭 LLM 本身回答）。
- 之后可通过命令行手动增量同步：

```bash
python -m csm_llm_qa.sync_wiki                 # 增量
python -m csm_llm_qa.sync_wiki --force         # 强制重建
python -m csm_llm_qa.sync_wiki --wiki ./docs --store ./.csm_llm_qa/vector_store

# 通过 wiki_source.json 检查远程更新并按需拉取
python -m csm_llm_qa.sync_wiki --remote
```

或在代码中：

```python
qa.sync_wiki(force=False)
```

---

## 提示词

库内置一段针对 **CSM/LabVIEW + RAG** 的中文 system prompt（详见 [`csm_llm_qa/prompts.py`](csm_llm_qa/prompts.py) 的 `DEFAULT_SYSTEM_PROMPT`）。

如需替换为通用领域 / 英文 / 自定义风格，传入 `system_prompt=` 即可：

```python
qa = CSM_QA(api_key="sk", system_prompt="You are a helpful general-purpose assistant.")
```

---

## 贡献 / 开发

请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

---

## License

MIT