From 2285c302570d9d3976674e08d835e8aaf0ac5a1b Mon Sep 17 00:00:00 2001
From: webbrain-one <295484252+webbrain-one@users.noreply.github.com>
Date: Wed, 29 Jul 2026 00:36:03 +0300
Subject: [PATCH] docs: add Spanish README

---
 README.es-ES.md | 327 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 327 insertions(+)
 create mode 100644 README.es-ES.md

diff --git a/README.es-ES.md b/README.es-ES.md
new file mode 100644
index 0000000..264c31c
--- /dev/null
+++ b/README.es-ES.md
@@ -0,0 +1,327 @@
+# Guía de Implementación de Chat con LLM
+
+![](./docs/imgs/intro.png)
+
+[Video Tutorial Parte 1 haz clic aquí](https://youtu.be/DzA1zo9vEZ4)
+
+[Ver PDF haz clic aquí](./docs/docker.pdf)
+
+[Ver Hoja de Ruta Detallada haz clic aquí](./docs/roadmap/index.md)
+
+![](./docs/imgs/intro-2.png)
+
+[Video Tutorial Parte 2 haz clic aquí](https://youtu.be/NdlS6BmYvW4)
+
+[Ver PDF Parte 2 haz clic aquí](./db-llm/db-llm.pdf)
+
+## Índice
+- [Introducción](#giới-thiệu)
+- [Arquitectura del Sistema](#kiến-trúc-hệ-thống)
+- [Requisitos del Sistema](#yêu-cầu-hệ-thống)
+- [Instalación y Despliegue](#cài-đặt-và-triển-khai)
+- [Detalle de los Componentes](#chi-tiết-các-component)
+- [Documentación de Referencia](#tài-liệu-tham-khảo)
+
+## Introducción
+
+Este proyecto es un sistema de chat integrado con un modelo de lenguaje extenso (LLM) utilizando:
+- Frontend: Next.js 15+ con App Router
+- Backend: FastAPI 
+- LLM: Ollama con el modelo Qwen
+- Base de datos: SQLite con SQLModel
+
+## Arquitectura del Sistema
+
+```mermaid
+graph LR
+    A[User Query] --> B[FastAPI Backend]
+    B --> C[Template Engine]
+    C --> D[LangChain Chain]
+    D --> E[Ollama LLM]
+    D --> F[(SQLite DB)]
+    
+    subgraph Template Processing
+        C --> G[PromptTemplate]
+        G --> H[Table Info]
+        H --> I[Question]
+    end
+    
+    subgraph LangChain Pipeline
+        D --> J[llm_chain]
+        J --> K[StrOutputParser]
+    end
+    
+    subgraph Database Operations
+        F --> L[Store Chat]
+        F --> M[Execute SQL]
+    end
+```
+
+## Requisitos del Sistema
+
+- Docker y Docker Compose
+- Node.js 18+ (para desarrollo)
+- Python 3.11+ (para desarrollo)
+- Git
+
+## Instalación y Despliegue
+
+### 1. Clonar el repositorio
+
+```bash
+git clone <repository-url>
+cd <project-folder>
+```
+
+### 2. Estructura del proyecto
+
+```
+.
+├── docker-compose.yml
+├── fastapi/
+│   ├── Dockerfile
+│   ├── app.py
+│   ├── requirements.txt
+│   └── ...
+├── nextjs-app/
+│   ├── Dockerfile
+│   ├── package.json
+│   └── ...
+└── ollama/
+    ├── Dockerfile
+    └── pull-qwen.sh
+```
+
+### 3. Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  frontend:
+    build: ./nextjs-app
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./nextjs-app:/app
+    depends_on:
+      - backend
+
+  backend:
+    build: ./fastapi
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./fastapi:/app
+    depends_on:
+      - ollama-server
+
+  ollama-server:
+    build: ./ollama
+    volumes:
+      - ollama_data:/root/.ollama
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+
+volumes:
+  ollama_data:
+```
+
+## Detalle de los Componentes
+
+### FastAPI Backend
+
+El backend de FastAPI procesa las solicitudes del frontend e interactúa con el LLM de Ollama. El código principal se encuentra en `app.py`:
+
+```python
+1:109:fastapi/app.py
+import requests
+from fastapi import FastAPI, Response
+
+# Database
+from db import (
+    create_chat,
+    get_all_chats,
+    get_chat_by_id,
+    delete_chat,
+    DataChat,
+    path_db
+@app.get('/ask')
+def ask(prompt :str):
+# Langchain
+from langchain_ollama import OllamaLLM # Ollama model
+from langchain_ollama.llms import BaseLLM # Lớp cơ sở cho LLM
+from langchain.chains.llm import LLMChain # xâu chuỗi các LLM
+from langchain.chains.sql_database.query import create_sql_query_chain # tạo chuỗi truy vấn dữ liệu llm
+from langchain.prompts import PromptTemplate # tạo khuôn mẫu
+from langchain_community.tools import QuerySQLDatabaseTool # công cụ truy vấn dữ liệu
+from langchain.sql_database import SQLDatabase # cơ sở dữ liệu
+from langchain_core.output_parsers import StrOutputParser, PydanticOutputParser # xuất kết quả ra định dạng chuỗi
+from langchain_core.runnables import RunnablePassthrough # truyền dữ liệu đi xa
+from operator import itemgetter # lấy giá trị từ dict
+# Cache
+from langchain.cache import InMemoryCache
+from langchain.globals import set_llm_cache
+#-----------------------------------------------------------------
+llm = OllamaLLM(
+# Utility
+from utils import get_sql_from_answer_llm
+)
+#test on docker
+url_docker = "http://ollama-server:11434"
+#test on local
+url_local = "http://localhost:11434"
+model = "qwen2.5-coder:0.5b"
+app = FastAPI()
+llm = OllamaLLM(
+    base_url=url_local, 
+    model=model
+)
+@app.get('/')
+cache = InMemoryCache()
+set_llm_cache(cache)
+
+@app.get('/ask')
+template = PromptTemplate.from_template(
+    """
+    Tôi có bảng sau đây là: {tables}
+    Hãy tạo câu truy vấn dữ liệu cho câu hỏi sau:
+    {question}
+
+    Trả lời ngay:
+    """
+)
+# nếu câu hỏi không liên quan đến các bảng dữ liệu trên thì trả lời "Không liên quan đến các bảng dữ liệu trên", và nếu câu hỏi gây nguy hiểm đến dữ liệu thì trả lời "Không trả lời câu hỏi này"
+
+llm_chain = (
+    template |
+    llm |
+    StrOutputParser()
+)
+
+db = SQLDatabase.from_uri(f"sqlite:///{path_db}")
+
+
+app = FastAPI()
+
+
+
+
+@app.get('/')
+def home():
+    return {"hello" : "World"}
+
+@app.get('/ask')
+def ask(prompt :str):
+    # name of the service is ollama-server, is hostname by bridge to connect same network
+    # res = requests.post('http://ollama-server:11434/api/generate', json={
+    #     "prompt": prompt,
+    #     "stream" : False,
+    #     "model" : "qwen2.5-coder:0.5b"
+    # })
+
+    res = llm_chain.invoke({
+        "tables": f'''{db.get_table_info(db.get_usable_table_names())}''',
+        "question": prompt
+    })
+    
+    response = ""
+    if isinstance(res, str):
+        response = res
+    else:
+        response = res.text
+        
+    # Store chat in database
+    chat = create_chat(message=prompt, response=response)
+
+    try:
+        data_db = db.run(get_sql_from_answer_llm(response))
+    except Exception as e:
+        data_db = str(e)
+    
+    return {
+        "answer": response, 
+        "data_db": data_db
+    }
+```
+
+Principales características implementadas:
+- Integración de LangChain para interactuar con Ollama
+- Caché de respuestas del LLM para mejorar el rendimiento
+- Generación de consultas SQL a partir de la entrada del usuario
+- Manejo de errores para operaciones de base de datos
+
+### Ollama Server
+
+El servidor de Ollama ejecuta el modelo Qwen y expone una API. La configuración está en `pull-qwen.sh`:
+
+```bash
+1:14:ollama/pull-qwen.sh
+
+./bin/ollama serve &
+
+pid=$!
+
+sleep 5
+
+echo "Pulling qwen2.5-coder model"
+ollama pull qwen2.5-coder:0.5b
+
+
+wait $pid
+```
+
+
+### Next.js Frontend
+
+El frontend utiliza Next.js 13+ con App Router y Tailwind CSS. Referencia de dependencias en:
+
+```json
+1:24:nextjs-app/package.json
+{
+  "name": "nextjs-app",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "react": "19.0.0-rc-66855b96-20241106",
+    "react-dom": "19.0.0-rc-66855b96-20241106",
+    "next": "15.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "postcss": "^8",
+    "tailwindcss": "^3.4.1"
+  }
+}
+```
+
+
+## Documentación de Referencia
+
+- [Documentación de FastAPI](https://fastapi.tiangolo.com/)
+- [Documentación de Next.js](https://nextjs.org/docs)
+- [Ollama GitHub](https://github.com/ollama/ollama)
+- [Documentación de LangChain](https://python.langchain.com/docs/get_started/introduction.html)
+- [Documentación de SQLModel](https://sqlmodel.tiangolo.com/)
+
+## Contribuciones
+
+Por favor, consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obtener más detalles sobre el proceso de contribución de código.
+
+## Licencia
+
+Este proyecto está bajo la licencia MIT. Consulte el archivo [LICENSE](LICENSE) para más detalles.