Milvus

Máy chủ MCP cho Milvus

Giao thức Ngữ cảnh Mô hình (MCP) là một giao thức mở cho phép tích hợp liền mạch giữa các ứng dụng LLM với các nguồn dữ liệu và công cụ bên ngoài. Dù bạn đang xây dựng một IDE hỗ trợ AI, nâng cao giao diện trò chuyện hay tạo quy trình làm việc AI tùy chỉnh, MCP cung cấp một cách thức chuẩn hóa để kết nối LLM với ngữ cảnh chúng cần.

Kho lưu trữ này chứa một máy chủ MCP cung cấp quyền truy cập vào chức năng cơ sở dữ liệu vector Milvus.

Điều kiện tiên quyết

Trước khi sử dụng máy chủ MCP này, hãy đảm bảo bạn có:

• Python 3.10 trở lên
• Một phiên bản Milvus đang chạy (cục bộ hoặc từ xa)
• uv đã được cài đặt (khuyến nghị để chạy máy chủ)

Cách sử dụng

Cách khuyến nghị để sử dụng máy chủ MCP này là chạy trực tiếp với uv mà không cần cài đặt. Đây là cách cả Claude Desktop và Cursor được cấu hình để sử dụng trong các ví dụ bên dưới.

Nếu bạn muốn sao chép kho lưu trữ:

git clone https://github.com/zilliztech/mcp-server-milvus.git
cd mcp-server-milvus

Sau đó bạn có thể chạy máy chủ trực tiếp:

uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

Ngoài ra, bạn có thể thay đổi tệp .env trong thư mục src/mcp_server_milvus/ để đặt các biến môi trường và chạy máy chủ bằng lệnh sau:

uv run src/mcp_server_milvus/server.py

Quan trọng: tệp .env sẽ có mức ưu tiên cao hơn các đối số dòng lệnh.

Chế độ chạy

Máy chủ hỗ trợ hai chế độ chạy: stdio (mặc định) và SSE (Server-Sent Events).

Chế độ Stdio (Mặc định)

• Mô tả: Giao tiếp với máy khách qua đầu vào/đầu ra tiêu chuẩn. Đây là chế độ mặc định nếu không có chế độ nào được chỉ định.

• Cách sử dụng:

  uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530
  

Chế độ SSE

• Mô tả: Sử dụng HTTP Server-Sent Events để giao tiếp. Chế độ này cho phép nhiều máy khách kết nối qua HTTP và phù hợp cho các ứng dụng dựa trên web.

• Cách sử dụng:

  uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
  

  • --sse: Bật chế độ SSE.
  • --port: Chỉ định cổng cho máy chủ SSE (mặc định: 8000).

• Gỡ lỗi ở chế độ SSE:

  Nếu bạn muốn gỡ lỗi ở chế độ SSE, sau khi khởi động dịch vụ SSE, hãy nhập lệnh sau:

  mcp dev src/mcp_server_milvus/server.py
  

  Đầu ra sẽ tương tự như:

  % mcp dev src/mcp_server_milvus/merged_server.py
  Starting MCP inspector...
  ⚙️ Proxy server listening on port 6277
  🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
  

  Sau đó bạn có thể truy cập MCP Inspector tại http://127.0.0.1:6274 để kiểm tra.

Chế độ HTTP có thể truyền phát

• Mô tả: Sử dụng HTTP với hỗ trợ truyền phát để giao tiếp. Đây là phương thức truyền tải được khuyến nghị cho triển khai sản xuất và hỗ trợ cả hoạt động có trạng thái và không trạng thái.

• Cách sử dụng:

  uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
  

  • --streamable-http: Bật chế độ HTTP có thể truyền phát.
  • --port: Chỉ định cổng cho máy chủ (mặc định: 8000).
  • --stateless: Cờ tùy chọn cho chế độ không trạng thái (không duy trì phiên).

• Chế độ không trạng thái:

  uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000
  

Ứng dụng được hỗ trợ

Máy chủ MCP này có thể được sử dụng với nhiều ứng dụng LLM khác nhau hỗ trợ Giao thức Ngữ cảnh Mô hình:

• Claude Desktop: Ứng dụng máy tính để bàn của Anthropic dành cho Claude
• Cursor: Trình soạn thảo mã hỗ trợ AI với hỗ trợ MCP
• Máy khách MCP tùy chỉnh: Bất kỳ ứng dụng nào triển khai đặc tả máy khách MCP

Sử dụng với Claude Desktop

Cấu hình cho các chế độ khác nhau

Cấu hình chế độ SSE

Thực hiện theo các bước sau để cấu hình Claude Desktop cho chế độ SSE:

1. Cài đặt Claude Desktop từ https://claude.ai/download.
2. Mở tệp cấu hình Claude Desktop của bạn:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Thêm cấu hình sau cho chế độ SSE:

{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cấu hình chế độ HTTP có thể truyền phát

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

4. Khởi động lại Claude Desktop để áp dụng các thay đổi.

Cấu hình chế độ Stdio

Đối với chế độ stdio, thực hiện theo các bước sau:

1. Cài đặt Claude Desktop từ https://claude.ai/download.
2. Mở tệp cấu hình Claude Desktop của bạn:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Thêm cấu hình sau cho chế độ stdio:

{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://localhost:19530"
      ]
    }
  }
}

4. Khởi động lại Claude Desktop để áp dụng các thay đổi.

Sử dụng với Cursor

Cursor cũng hỗ trợ các công cụ MCP. Bạn có thể tích hợp máy chủ Milvus MCP của mình với Cursor bằng cách thực hiện theo các bước sau:

Các bước tích hợp

1. Mở Cursor Settings > MCP
2. Nhấp vào Add new global MCP server
3. Sau khi nhấp, nó sẽ tự động chuyển hướng bạn đến tệp mcp.json, tệp này sẽ được tạo nếu chưa tồn tại

Cấu hình tệp mcp.json

Đối với chế độ Stdio:

Ghi đè tệp mcp.json bằng nội dung sau:

{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://127.0.0.1:19530"
      ]
    }
  }
}

Đối với chế độ SSE:

1. Khởi động dịch vụ bằng cách chạy lệnh sau:

   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
   

   Lưu ý: Thay thế http://your_sse_host bằng địa chỉ máy chủ SSE thực tế của bạn và port bằng số cổng cụ thể bạn đang sử dụng.

2. Khi dịch vụ đã hoạt động, ghi đè tệp mcp.json bằng nội dung sau:

   {
       "mcpServers": {
         "milvus-sse": {
           "url": "http://your_sse_host:port/sse",
           "disabled": false,
           "autoApprove": []
         }
       }
   }
   

Đối với chế độ HTTP có thể truyền phát:

1. Khởi động dịch vụ:

   uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port
   

2. Cập nhật mcp.json:

   {
     "mcpServers": {
       "milvus-streamable-http": {
         "url": "http://your_host:port/mcp",
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

Hoàn tất tích hợp

Sau khi hoàn thành các bước trên, khởi động lại Cursor hoặc tải lại cửa sổ để đảm bảo cấu hình có hiệu lực.

Xác minh tích hợp

Để xác minh rằng Cursor đã tích hợp thành công với máy chủ Milvus MCP của bạn:

1. Mở Cursor Settings > MCP
2. Kiểm tra xem "milvus", "milvus-sse" hoặc "milvus-streamable-http" có xuất hiện trong danh sách không (tùy thuộc vào chế độ bạn đã chọn)
3. Xác nhận rằng các công cụ liên quan được liệt kê (ví dụ: milvus_list_collections, milvus_vector_search, v.v.)
4. Nếu máy chủ được bật nhưng hiển thị lỗi, hãy kiểm tra phần Khắc phục sự cố bên dưới

Công cụ có sẵn

Máy chủ cung cấp các công cụ sau:

Thao tác tìm kiếm và truy vấn

• milvus_text_search: Tìm kiếm tài liệu bằng tìm kiếm toàn văn

  • Tham số:
    • collection_name: Tên của collection cần tìm kiếm
    • query_text: Văn bản cần tìm kiếm
    • limit: Số lượng kết quả tối đa trả về (mặc định: 5)
    • output_fields: Các trường cần bao gồm trong kết quả
    • drop_ratio: Tỷ lệ các thuật ngữ tần suất thấp cần bỏ qua (0.0-1.0) (mặc định: 0.2)

• milvus_vector_search: Thực hiện tìm kiếm tương đồng vector trên một collection

  • Tham số:
    • collection_name: Tên của collection cần tìm kiếm
    • vector: Vector truy vấn
    • vector_field: Tên trường cho tìm kiếm vector (mặc định: "vector")
    • limit: Số lượng kết quả tối đa trả về (mặc định: 5)
    • output_fields: Các trường cần bao gồm trong kết quả
    • filter_expr: Biểu thức lọc
    • metric_type: Độ đo khoảng cách (COSINE, L2, IP) (mặc định: "COSINE")
    • radius: Giới hạn dưới tùy chọn cho tìm kiếm phạm vi (mặc định: None)
    • range_filter: Giới hạn trên tùy chọn cho tìm kiếm phạm vi (mặc định: None)

• milvus_hybrid_search: Thực hiện tìm kiếm kết hợp trên một collection

  • Tham số:
    • collection_name: Tên của collection cần tìm kiếm
    • query_text: Truy vấn văn bản để tìm kiếm
    • text_field: Tên trường cho tìm kiếm văn bản
    • vector: Vector của truy vấn văn bản
    • vector_field: Tên trường cho tìm kiếm vector
    • limit: Số lượng kết quả tối đa trả về (mặc định: 5)
    • output_fields: Các trường cần bao gồm trong kết quả
    • filter_expr: Biểu thức lọc
    • sparse_radius: Giới hạn dưới tùy chọn cho tìm kiếm phạm vi thưa (mặc định: None)
    • sparse_range_filter: Giới hạn trên tùy chọn cho tìm kiếm phạm vi thưa (mặc định: None)
    • dense_radius: Giới hạn dưới tùy chọn cho tìm kiếm phạm vi dày đặc (mặc định: None)
    • dense_range_filter: Giới hạn trên tùy chọn cho tìm kiếm phạm vi dày đặc (mặc định: None)

• milvus_text_similarity_search: Thực hiện tìm kiếm tương đồng văn bản trên một collection

  Lưu ý: Công cụ này chỉ được hỗ trợ trong Milvus 2.6.0 trở lên. Và bạn cần đặt hàm nhúng tại máy chủ Milvus. Xem Hàm nhúng để biết thêm chi tiết.

  • Tham số:
    • collection_name: Tên của collection cần tìm kiếm
    • query_text: Truy vấn văn bản cho tìm kiếm tương đồng
    • anns_field: Tên trường cho tìm kiếm văn bản
    • limit: Số lượng kết quả tối đa trả về (mặc định: 5)
    • output_fields: Các trường cần bao gồm trong kết quả
    • metric_type: Độ đo khoảng cách (COSINE, L2, IP) (mặc định: "COSINE")
    • filter_expr: Biểu thức lọc tùy chọn
    • radius: Giới hạn dưới tùy chọn cho tìm kiếm phạm vi (mặc định: None)
    • range_filter: Giới hạn trên tùy chọn cho tìm kiếm phạm vi (mặc định: None)

• milvus_query: Truy vấn collection sử dụng biểu thức lọc

  • Tham số:
    • collection_name: Tên của collection cần truy vấn
    • filter_expr: Biểu thức lọc (ví dụ: 'age > 20')
    • output_fields: Các trường cần bao gồm trong kết quả
    • limit: Số lượng kết quả tối đa trả về (mặc định: 10)

Quản lý Collection

• milvus_list_collections: Liệt kê tất cả các collection trong cơ sở dữ liệu

• milvus_create_collection: Tạo một collection mới với thiết lập nhanh hoặc lược đồ tùy chỉnh

  • Tham số:
    • collection_name: Tên cho collection mới
    • auto_id: có tự động tạo id hay không, mặc định là True
    • dimension: số chiều vector, mặc định là 768; dành cho thiết lập nhanh và sẽ bị bỏ qua nếu field_schema được cung cấp
    • primary_field_name: tên của trường chính, mặc định là "id"; dành cho thiết lập nhanh và sẽ bị bỏ qua nếu field_schema được cung cấp
    • vector_field_name: tên của trường vector, mặc định là "vector"; dành cho thiết lập nhanh và sẽ bị bỏ qua nếu field_schema được cung cấp
    • metric_type: loại độ đo, mặc định là "COSINE"; dành cho thiết lập nhanh và sẽ bị bỏ qua nếu field_schema được cung cấp
    • field_schema: Danh sách lược đồ trường, mỗi phần tử là một từ điển với các khóa sau:
      • name: tên của trường
      • type: loại của trường
    • index_params: Danh sách tùy chọn các tham số chỉ mục, mỗi phần tử là một từ điển với các khóa sau:
      • field_name: tên của trường cần đánh chỉ mục
      • index_type: loại chỉ mục
      • **kwargs: các tham số chỉ mục tùy chọn khác
    • other_kwargs: Các đối số từ khóa bổ sung cho việc tạo collection

• milvus_load_collection: Tải một collection vào bộ nhớ để tìm kiếm và truy vấn

  • Tham số:
    • collection_name: Tên của collection cần tải
    • replica_number: Số lượng bản sao (mặc định: 1)

• milvus_release_collection: Giải phóng một collection khỏi bộ nhớ

  • Tham số:
    • collection_name: Tên của collection cần giải phóng

• milvus_get_collection_info: Liệt kê thông tin chi tiết như lược đồ, thuộc tính, ID collection và siêu dữ liệu khác của một collection cụ thể.

  • Tham số:
    • collection_name: Tên của collection cần lấy thông tin chi tiết

Thao tác dữ liệu

• milvus_insert_data: Chèn dữ liệu vào một collection

  • Tham số:
    • collection_name: Tên của collection
    • data: Từ điển ánh xạ tên trường tới danh sách các giá trị

• milvus_delete_entities: Xóa các thực thể khỏi collection dựa trên biểu thức lọc

  • Tham số:
    • collection_name: Tên của collection
    • filter_expr: Biểu thức lọc để chọn các thực thể cần xóa

Biến môi trường

• MILVUS_URI: URI máy chủ Milvus (có thể đặt thay vì --milvus-uri)
• MILVUS_TOKEN: Mã thông báo xác thực tùy chọn
• MILVUS_DB: Tên cơ sở dữ liệu (mặc định là "default")

Phát triển

Để chạy máy chủ trực tiếp:

uv run server.py --milvus-uri http://localhost:19530

Ví dụ

Sử dụng Claude Desktop

Ví dụ 1: Liệt kê các Collection

What are the collections I have in my Milvus DB?

Claude sau đó sẽ sử dụng MCP để kiểm tra thông tin này trên Milvus DB của bạn.

I'll check what collections are available in your Milvus database.

Here are the collections in your Milvus database:

1. rag_demo
2. test
3. chat_messages
4. text_collection
5. image_collection
6. customized_setup
7. streaming_rag_demo

Ví dụ 2: Tìm kiếm Tài liệu

Find documents in my text_collection that mention "machine learning"

Claude sẽ sử dụng khả năng tìm kiếm toàn văn của Milvus để tìm các tài liệu liên quan:

I'll search for documents about machine learning in your text_collection.

> View result from milvus-text-search from milvus (local)

Here are the documents I found that mention machine learning:
[Results will appear here based on your actual data]

Sử dụng Cursor

Ví dụ: Tạo một Collection

Trong Cursor, bạn có thể yêu cầu:

Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)

Cursor sẽ sử dụng máy chủ MCP để thực thi thao tác này:

I'll create a new collection called 'articles' with the specified fields.

Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float vector[128]

Khắc phục sự cố

Các vấn đề thường gặp

Lỗi kết nối

Nếu bạn thấy lỗi như "Failed to connect to Milvus server":

1. Xác minh phiên bản Milvus của bạn đang chạy: docker ps (nếu dùng Docker)
2. Kiểm tra URI đã chính xác trong cấu hình của bạn chưa
3. Đảm bảo không có quy tắc tường lửa nào chặn kết nối
4. Thử dùng 127.0.0.1 thay vì localhost trong URI

Vấn đề xác thực

Nếu bạn thấy lỗi xác thực:

1. Xác minh MILVUS_TOKEN của bạn là chính xác
2. Kiểm tra xem phiên bản Milvus của bạn có yêu cầu xác thực không
3. Đảm bảo bạn có quyền phù hợp cho các thao tác bạn đang cố thực hiện

Không tìm thấy công cụ

Nếu các công cụ MCP không xuất hiện trong Claude Desktop hoặc Cursor:

1. Khởi động lại ứng dụng
2. Kiểm tra nhật ký máy chủ để tìm lỗi
3. Xác minh máy chủ MCP đang chạy đúng cách
4. Nhấn nút làm mới trong cài đặt MCP (đối với Cursor)

Nhận trợ giúp

Nếu bạn vẫn gặp sự cố:

1. Kiểm tra GitHub Issues để tìm các vấn đề tương tự
2. Tham gia Milvus Community Discord để được hỗ trợ
3. Tạo một issue mới với thông tin chi tiết về vấn đề của bạn