README.md

---
title: 食物卡路里檢測器
emoji: 🍎
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.42.0
app_file: app.py
pinned: false
license: mit
short_description: 計算上傳照片中食物的熱量
---

# 🍎 食物卡路里檢測器

這是一個基於Gradio和Google AI的智慧食物卡路里檢測應用程式。使用者可以上傳食物照片，AI會自動識別食物種類並估算卡路里含量。

## ✨ 功能特色

- 📸 **智慧食物識別**：使用Google Gemini AI識別照片中的食物
- 🔢 **卡路里估算**：自動計算食物的大概卡路里含量
- 📊 **營養資訊**：提供基本的營養價值說明
- 🚫 **非食物檢測**：能夠識別並提醒非食物圖片
- 🌐 **繁體中文介面**：完全繁體中文使用者介面
- 🚀 **簡易部署**：支援HuggingFace Spaces一鍵部署

## 🛠️ 技術棧

- **前端框架**：Gradio
- **AI模型**：Google Gemini 1.5 Flash
- **圖片處理**：Pillow (PIL)
- **環境管理**：uv + venv
- **部署平台**：HuggingFace Spaces

## 📋 環境需求

- Python 3.8+
- Google AI API Key
- HuggingFace Token（用於部署）

## 🚀 快速開始

### 1. 克隆專案

```bash
git clone <your-repo-url>
cd CalorieApp
```

### 2. 設定Python環境

```bash
# 使用uv建立虛擬環境
uv venv .venv

# 啟動虛擬環境
source .venv/bin/activate  # Linux/Mac
# 或
.venv\\Scripts\\activate  # Windows
```

### 3. 安裝依賴

```bash
uv pip install -r requirements.txt
```

### 4. 設定環境變數

```bash
# 複製環境變數範例檔案
cp .env.example .env

# 編輯.env檔案，填入你的API金鑰
nano .env
```

在`.env`檔案中填入：
```env
GOOGLE_API_KEY=your_google_api_key_here
HF_TOKEN=your_huggingface_token_here
```

### 5. 執行應用程式

```bash
python app.py
```

應用程式將在 `http://localhost:7860` 啟動。

## 🔑 取得API金鑰

### Google AI API Key
1. 前往 [Google AI Studio](https://makersuite.google.com/app/apikey)
2. 登入你的Google帳號
3. 建立新的API金鑰
4. **本機開發**：將金鑰加入`.env`檔案
5. **HuggingFace部署**：在Space設定中加入環境變數 `GOOGLE_API_KEY`

### HuggingFace Token（僅用於程式化部署）
1. 前往 [HuggingFace設定](https://huggingface.co/settings/tokens)
2. 建立新的Access Token
3. 選擇適當的權限範圍

## 🌐 HuggingFace Spaces 部署說明

此應用程式已針對HuggingFace Spaces進行優化：

### 環境變數設定
在你的Space設定中加入以下環境變數：
- `GOOGLE_API_KEY`: 你的Google AI API金鑰

### 自動部署
1. Fork或克隆此repository到你的HuggingFace Space
2. 設定環境變數
3. 應用程式將自動建置和部署

## 🌐 部署到HuggingFace Spaces

### 方法一：直接上傳

1. 在HuggingFace建立新的Space
2. 選擇Gradio作為SDK
3. 上傳所有專案檔案
4. 在Space設定中加入環境變數：
   - `GOOGLE_API_KEY`: 你的Google AI API金鑰

### 方法二：Git Repository

1. 在HuggingFace建立新的Space
2. 選擇「Git repository」選項
3. 將此專案推送到HuggingFace的Git repository
4. 設定環境變數（同上）

## 📁 專案結構

```
CalorieApp/
├── app.py              # 主要應用程式
├── requirements.txt    # Python依賴套件
├── .env.example       # 環境變數範例
├── .gitignore         # Git忽略檔案
├── README.md          # 專案說明文件
└── .venv/             # Python虛擬環境
```

## 🎯 使用方法

1. **上傳圖片**：點擊上傳區域選擇食物照片
2. **自動分析**：上傳後AI會自動開始分析
3. **查看結果**：右側會顯示詳細的分析結果，包括：
   - 食物名稱
   - 估算份量  
   - 預估卡路里
   - 營養說明

## ⚠️ 注意事項

- 卡路里估算僅供參考，實際數值可能因烹飪方式和份量而有所差異
- 建議上傳清晰、光線充足的食物照片以獲得更準確的結果
- AI可能對某些特殊或混合食物的識別有限制
- 請確保遵守Google AI的使用條款和限制

## 🔧 故障排除

### 常見問題

**Q: 顯示「Google AI模型未正確初始化」錯誤**
A: 請檢查`.env`檔案中的`GOOGLE_API_KEY`是否正確設定

**Q: 上傳圖片後沒有反應**
A: 請確認圖片格式支援（JPG、PNG等）且檔案大小合理

**Q: 分析結果不準確**
A: AI模型的準確度會因圖片品質、食物種類等因素而變化，建議使用清晰的照片

## 🤝 貢獻

歡迎提交Issue和Pull Request來改善這個專案！

## 📄 授權

本專案採用MIT授權條款。

## 📞 聯絡資訊

如有任何問題或建議，請透過GitHub Issues聯絡我們。