Khắc phục lỗi WeaviateConnectionError: 'Failed to connect to localhost:8080'

Thông báo lỗi

Lỗi này có thể xảy ra với bất kỳ ai: bạn khởi chạy pipeline RAG (Retrieval-Augmented Generation), mong đợi dữ liệu được truy xuất mượt mà, nhưng terminal lại báo lỗi kết nối. Mọi thứ sụp đổ ngay khi bạn khởi tạo vector database client. Thông thường, traceback sẽ trông như thế này:

weaviate.exceptions.WeaviateConnectionError: Failed to connect to Weaviate at http://localhost:8080. 
Error: HTTPConnectionPool(host='localhost', port=8080): 
Max retries exceeded with url: /v1/.well-known/ready 
(Caused by NewConnectionError: Failed to establish a new connection: [Errno 111] Connection refused)

Điều gì đang làm gián đoạn kết nối?

Nói một cách đơn giản, lỗi này có nghĩa là script Python của bạn đang "gõ cửa" http://localhost:8080, nhưng không có ai trả lời. Khi làm việc với các pipeline RAG được Docker hóa (Dockerized), sự im lặng này thường bắt nguồn từ một trong bốn vấn đề cụ thể sau:

• Container là một "bóng ma": Container Docker Weaviate của bạn không chạy hoặc đã bị crash trong quá trình khởi động.
• Bẫy "Localhost": Bạn đang chạy Python bên trong một container, nhưng nó lại cố gắng tìm Weaviate bên trong môi trường nhỏ bé của chính nó thay vì máy host.
• Script chạy "quá nhanh": Mã Python của bạn đã sẵn sàng làm việc, nhưng Weaviate vẫn đang bận tải các index hoặc các module ML nặng.
• Nhầm lẫn cổng (Port): Một dịch vụ khác—chẳng hạn như một server phát triển đang chạy ngầm—đang chiếm dụng cổng 8080, hoặc cấu hình mapping trong file docker-compose.yml của bạn bị sai.

Các bước khắc phục cụ thể

1. Kiểm tra trạng thái Container

Bắt đầu với những thứ cơ bản. Hãy xác nhận rằng Weaviate thực sự đang hoạt động trên hệ thống của bạn. Chạy lệnh này trong terminal:

docker ps

Quét danh sách để tìm image weaviate. Nếu nó bị thiếu, hãy khởi động lại các dịch vụ của bạn:

docker-compose up -d

Đôi khi các container tự thoát mà không báo trước do giới hạn bộ nhớ hoặc thiếu API key cho các nhà cung cấp như OpenAI. Nếu nó tiếp tục biến mất, hãy xem log để tìm nguyên nhân chính xác:

docker-compose logs weaviate

2. Kết nối khoảng cách mạng Docker

Nếu cả ứng dụng Python và Weaviate của bạn đều đang chạy trong Docker, localhost là kẻ thù của bạn. Trong một mạng Docker, các container tự xem mình là localhost. Để giao tiếp với một "hàng xóm", chúng phải sử dụng tên dịch vụ (service name).

Kiểm tra file docker-compose.yml của bạn. Nó thường trông như thế này:

services:
  weaviate:
    image: semitechnologies/weaviate:1.24.1
    ports:
      - "8080:8080"
  app:
    build: .
    depends_on:
      - weaviate

Bạn cần cập nhật chuỗi kết nối Python của mình. Hãy thay thế địa chỉ chung bằng tên dịch vụ được định nghĩa trong file YAML của bạn:

# Lệnh này sẽ thất bại bên trong Docker
client = weaviate.Client("http://localhost:8080")

# Lệnh này hoạt động: "weaviate" khớp với tên dịch vụ
client = weaviate.Client("http://weaviate:8080")

3. Để Database có thời gian "thở"

Các vector database không khởi động tức thì. Tùy thuộc vào phần cứng của bạn, Weaviate có thể mất từ 5 đến 15 giây để khởi tạo các plugin và xác minh các shard hiện có. Nếu script của bạn gọi client.is_ready() quá sớm, endpoint /v1/.well-known/ready sẽ đơn giản là bỏ qua yêu cầu.

Thêm một vòng lặp thử lại (retry loop) đơn giản vào thiết lập Python để giúp pipeline của bạn linh hoạt hơn:

import weaviate
import time
from weaviate.exceptions import WeaviateConnectionError

def connect_with_retry(url, retries=10, delay=2):
    for i in range(retries):
        try:
            client = weaviate.Client(url)
            if client.is_ready():
                print("Đã kết nối với Weaviate!")
                return client
        except WeaviateConnectionError:
            print(f"Đang chờ Weaviate... (Lần thử {i+1}/{retries})")
            time.sleep(delay)
    raise Exception("Kết nối thất bại sau 20 giây.")

client = connect_with_retry("http://localhost:8080")

4. Kiểm tra cấu hình Port Mapping

Đảm bảo file docker-compose.yml của bạn thực sự expose database ra máy host. Port mapping phải tuân theo mô hình Host:Container. Nó sẽ trông chính xác như thế này:

ports:
  - "8080:8080"

Nếu bạn đã thay đổi số đầu tiên—ví dụ: thành "9000:8080" để tránh xung đột—bạn phải cập nhật Python client để sử dụng http://localhost:9000.

Cách xác nhận việc sửa lỗi

Trước khi quay lại với logic RAG, hãy sử dụng một lệnh curl đơn giản để kiểm tra tình hình. Việc này xác nhận rằng database có thể truy cập được từ terminal của bạn:

curl -i http://localhost:8080/v1/.well-known/ready

Bạn đang tìm kiếm kết quả HTTP/1.1 200 OK. Nếu bạn vẫn thấy thông báo "Connection Refused", vấn đề nằm ở cấu hình Docker của bạn, không phải ở mã Python. Khi lệnh curl thành công, hãy chạy một bài kiểm tra nhanh (sanity check) bằng Python để xác minh kết nối client đã ổn định.

Mẹo phòng ngừa

• Sử dụng Health Checks: Thêm một health check vào dịch vụ Weaviate của bạn trong Docker Compose. Điều này đảm bảo ứng dụng Python của bạn sẽ đợi cho đến khi database thực sự khỏe mạnh trước khi bắt đầu.
• Biến môi trường: Không bao giờ code cứng (hardcode) URL của bạn. Sử dụng file .env để bạn có thể dễ dàng chuyển đổi giữa localhost:8080 khi test cục bộ và weaviate:8080 cho môi trường production.
• Theo dõi Logs: Luôn mở một cửa sổ terminal để chạy docker-compose logs -f. Đây là cách nhanh nhất để phát hiện các sự cố kết nối ngay khi chúng xảy ra.