File size: 3,909 Bytes
55847d9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | # Agent Deployment Guide & Best Practices for Hugging Face Space
This codebase is configured for deployment on **Hugging Face Spaces**.
## 1. Deployment Configuration
### Target Space
- **Profile:** `Leon4gr45`
- **Space:** `Velo`
- **Full Identifier:** `Leon4gr45/Velo`
- **Frontend Port:** `7860` (mandatory for Hugging Face Spaces)
### Deployment Method
- **Docker SDK** — The application is built using a multi-stage Dockerfile (`Dockerfile`), building Vite static assets and serving them via Node.js / Express (`server.js`) on port 7860.
### HF Token
- Always read the token from environment variable `HF_TOKEN`.
- Never hardcode secret tokens in tracked files.
### Required Files
- `Dockerfile`: Multi-stage build for web application assets and Express runner.
- `server.js`: Web server serving static assets and API routes.
- `README.md`: Includes Hugging Face Space YAML frontmatter:
```yaml
---
title: Velo
sdk: docker
app_port: 7860
---
```
- `.hfignore`: Excludes `node_modules`, `.git`, build output artifacts, and logs from uploads.
- `Agent.md`: This deployment documentation.
---
## 2. API Exposure and Documentation
### Mandatory Endpoints
- **`/health`**
- Method: `GET`
- Purpose: Liveness & readiness check for Hugging Face Spaces.
- Returns: `{ "status": "ok", "service": "Velo" }` with HTTP 200.
- **`/api-docs`**
- Method: `GET`
- Purpose: Documents all available API endpoints.
- Reachable at: `https://Leon4gr45-Velo.hf.space/api-docs`
### Functional Endpoints
- **`/predict`**
- Method: `POST`
- Purpose: Story continuation and text prediction.
- Request Example:
```json
{
"prompt": "The old clock struck midnight as Elena entered the library...",
"maxLength": 100
}
```
- Response Example:
```json
{
"continuation": "A faint blue light gleamed from behind the bookshelf...",
"status": "success"
}
```
- **`/generate`**
- Method: `POST`
- Purpose: Generate narrative outlines and creative writing structures.
- Request Example:
```json
{
"genre": "Sci-Fi",
"topic": "First contact with an ancient artifact"
}
```
- Response Example:
```json
{
"genre": "Sci-Fi",
"topic": "First contact with an ancient artifact",
"outline": "Chapter 1: Discovery in the Kuiper Belt...",
"status": "success"
}
```
### OpenAI-Compatible Endpoints with Custom URL
- **`/v1/models`**
- Method: `GET`
- Purpose: List available models.
- **`/v1/chat/completions`**
- Method: `POST`
- Purpose: Chat completion interface matching the OpenAI API format.
- Custom URL Support: Accepts `custom_url` or `base_url` parameter in body or `X-Custom-Url` header to forward requests to custom upstream OpenAI-compatible endpoints.
- Request Example:
```json
{
"model": "velo-default",
"messages": [
{ "role": "user", "content": "Write a short scene." }
],
"custom_url": "https://api.openai.com/v1"
}
```
---
## 3. Deployment Workflow & Tricks
1. **Clean Hugging Face Repo (Precondition):**
```python
from huggingface_hub import HfApi
api = HfApi(token=token)
# Reset space repo if file limit exceeded
```
2. **Upload Codebase:**
```bash
hf upload Leon4gr45/Velo . --repo-type=space --exclude "node_modules/*" --exclude "dist/*" --exclude ".git/*"
```
3. **Stream Build and Run Logs:**
- Build logs (SSE):
```bash
curl -N -H "Authorization: Bearer <TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/Velo/logs/build"
```
- Run logs (SSE):
```bash
curl -N -H "Authorization: Bearer <TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/Velo/logs/run"
```
4. **Verify Health & OpenAI Endpoints:**
- Query `https://Leon4gr45-Velo.hf.space/health` and `https://Leon4gr45-Velo.hf.space/v1/chat/completions`.
|