# aiscript

**Repository Path**: andrewtestma/aiscript

## Basic Information

- **Project Name**: aiscript
- **Description**: AI剧本
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-25
- **Last Updated**: 2025-12-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

AIScript 部署与启动指南

概述
- 后端使用 `FastAPI` 与 `uvicorn`，入口为 `scripts/run_gateway.py`，应用对象位于 `services/gateway.py` 的 `app`。
- 默认监听 `127.0.0.1:8000`，健康检查为 `GET /health`，业务接口前缀为 `/api/v1`。
- 可选前端位于 `web` 目录（React + Vite），默认将请求指向后端 `http://127.0.0.1:8000`。

环境要求
- Python 3.10+（建议）
- Node.js 18+（仅在启用前端时需要）

后端安装
- 安装依赖（当前仓库未提供 `requirements.txt` 或 `pyproject.toml`，请按需安装）：
  - `pip install fastapi uvicorn neo4j pydantic`

后端配置（环境变量）
- 在 PowerShell 中使用 `$env:` 设置当前会话的环境变量。
- 知识图谱（Neo4j）（如启用 KG 接口）：
  - `$env:NEO4J_URI = "bolt://localhost:7687"`
  - `$env:NEO4J_USER = "neo4j"`
  - `$env:NEO4J_PASSWORD = "your_password"`
- LLM 提供方（按需选择其一）：
  - 使用占位/本地默认：
    - `$env:LLM_PROVIDER = "stub"`
  - 使用 OpenAI 兼容或 vLLM：
    - `$env:LLM_PROVIDER = "openai_compatible"`
    - `$env:OPENAI_BASE_URL = "http://localhost:8000"`（示例，替换为你的兼容端点）
    - `$env:OPENAI_API_KEY = "sk-xxxx"`
    - 可选：`$env:OPENAI_MODEL = "gpt-4o-mini"` 等
  - 使用 DashScope/通义千问：
    - `$env:DASHSCOPE_API_KEY = "xxx"`
    - 可选：`$env:DASHSCOPE_ENDPOINT = "https://dashscope.aliyuncs.com"`、`$env:DASHSCOPE_MODEL = "qwen-plus"`

启动后端服务
- 开发启动（推荐）：
  - `python scripts/run_gateway.py`
- 命令行直接启动（等价）：
  - `uvicorn services.gateway:app --host 127.0.0.1 --port 8000 --reload`
- 启动后访问：
  - 健康检查：`http://127.0.0.1:8000/health`
  - 示例接口：
    - `GET /api/v1/search?query=...`
    - `POST /api/v1/context/aggregate`
    - `POST /api/v1/inference/complete`
    - 小说相关：`GET /api/v1/novels/meta`、`GET /api/v1/novels/chapters`、`GET /api/v1/novels/chapter`
    - 清洗分段：`POST /api/v1/clean/segments`
    - KG（需 Neo4j）：`GET /api/v1/kg/person`、`GET /api/v1/kg/relations`、`GET /api/v1/kg/neighbors`

前端（可选）
- 切换到 `web` 目录：
  - `pnpm install`
  - 如需自定义后端地址（默认 `http://127.0.0.1:8000`）：
    - `$env:VITE_API_BASE = "http://127.0.0.1:8000"`
  - 启动开发服务器：
    - `pnpm dev`

生产部署建议
- 使用 `uvicorn` 生产模式（Linux 示例）：
  - `uvicorn services.gateway:app --host 0.0.0.0 --port 8000 --workers 2`
- 或结合 `gunicorn`（Linux）：
  - `gunicorn -k uvicorn.workers.UvicornWorker services.gateway:app -b 0.0.0.0:8000 -w 2`
- 请根据实际环境增加进程管理（如 `systemd`、`supervisor`）及反向代理（如 `nginx`）。

常见问题
- 依赖缺失：按文档安装后端依赖；如报导入错误，确认安装路径和虚拟环境。
- 端口占用：修改 `scripts/run_gateway.py` 或启动命令中的 `--port`。
- Neo4j 无法连接：确认数据库已启动、账号密码正确、网络可达。
- LLM 未配置：使用 `$env:LLM_PROVIDER = "stub"` 进行本地占位推理，或按需配置提供方及密钥。