docs: add non-Docker server startup guide

main
Bifang 2026-09-29 09:52:03 +08:00
parent dde3e12476
commit df81b0d209
1 changed files with 44 additions and 0 deletions

View File

@ -241,6 +241,50 @@ docker compose up -d
> Detailed deployment instructions: [Deployment Guide](./docs/deployment.md)
### 2. Non-Docker Deployment (Linux Server)
Run the FastAPI service directly on the server when you want to test without Docker. The commands below use NVIDIA as an example; use the matching `scripts/sync_*_env.sh` script for CPU or a vendor GPU backend (see the table in [Local Development](#local-development)).
**Requirements:** Python 3.10–3.12, `uv`, FFmpeg, and the server's supported accelerator driver/runtime. The default NVIDIA environment installs the CUDA 13.0 PyTorch/vLLM stack from the project lock file.
```bash
# From the project root
python3 --version
uv --version
# Install the NVIDIA environment. For CPU, use ./scripts/sync_cpu_env.sh.
./scripts/sync_gpu_env.sh
# Copy the sample settings, then edit .env if needed.
cp .env.example .env
```
Set `HOST=0.0.0.0` and `PORT=8000` in `.env` if you want to access the service from another machine. Set `API_KEY` to enable authentication; it is optional for a local test. Model files use `./models` by default. To store them elsewhere, set `MODELS_DIR`, `MODELSCOPE_CACHE`, and `MODELSCOPE_PATH` in `.env` as described in the sample file.
Download the models before starting so the first server launch does not wait for model downloads:
```bash
./scripts/download-models.sh --models-dir ./models --python-bin ./.venv/bin/python --mode local
```
This step requires access to ModelScope. If you skip it, `start.py` checks for missing models and attempts to download them during startup.
Start the service in the foreground and watch the startup logs:
```bash
./.venv/bin/python start.py
```
The default endpoint is `http://<server-ip>:8000`; open port `8000` in the server firewall if you are connecting remotely. Check the service and open the interactive API docs at `http://<server-ip>:8000/docs`. To test transcription with an audio file:
```bash
curl -X POST http://127.0.0.1:8000/v1/audio/transcriptions \
-H "Authorization: Bearer your_api_key" \
-F "file=@/path/to/test.wav"
```
Replace `your_api_key` with the value in `.env`. If `API_KEY` is unset, omit the `Authorization` header. Stop the foreground process with `Ctrl+C`.
### Local Development
**System Requirements:**