Hướng dẫn máy chủ tài nguyên 3D: Tìm kiếm, so sánh và tải xuống tài nguyên game từ 18 nguồn

3d-asset-server thực hiện gì

3d-asset-server cung cấp một ô tìm kiếm duy nhất cho mô hình 3D, vật liệu, kết cấu, HDRI, sprite, tài sản giao diện, âm thanh, phông chữ và các gói tài sản trò chơi. Công cụ tìm kiếm trên 18 nhà cung cấp, hợp nhất và xếp hạng kết quả, báo cáo trạng thái của từng nguồn, đồng thời tải tài sản khi nhà cung cấp cho phép tải trực tiếp.

Bạn có thể sử dụng dự án từ trình duyệt, với curl, thông qua giao diện dòng lệnh hoặc từ trợ lý AI được kết nối qua Model Context Protocol (MCP). Kết quả bao gồm thông tin giấy phép, trạng thái giá, yêu cầu ghi công, định dạng, độ phân giải và liên kết đến nhà cung cấp.

Cách thức tìm kiếm

Với mỗi truy vấn, máy chủ chọn các nhà cung cấp phù hợp và tìm kiếm song song. Mỗi nhà cung cấp có thời gian chờ riêng, vì vậy một trang web chậm hoặc không khả dụng sẽ không ngăn kết quả từ các nguồn khác hiển thị.

Kết quả được xếp hạng dựa trên mức độ liên quan của văn bản, thứ hạng của nhà cung cấp, việc kết quả đến từ API hay trình thu thập dữ liệu, khả năng cung cấp miễn phí, hỗ trợ tải trực tiếp và sự đa dạng của nguồn. Phản hồi cũng bao gồm báo cáo theo từng nhà cung cấp với các trạng thái như ok, error, timeout, skipped hoặc link.

Một số nhà cung cấp hỗ trợ tải trực tiếp. Poly Haven, ambientCG, Kenney, TextureCan và các tài sản miễn phí từ BlenderKit là những ví dụ. Các nhà cung cấp khác trả về đầy đủ siêu dữ liệu và liên kết đến trang tài sản, trong khi Fab, Poliigon và TurboSquid cung cấp liên kết đến các trang tìm kiếm riêng khi cơ chế bảo vệ bot ngăn việc tìm kiếm tự động.

Các nguồn được hỗ trợ

Danh mục nhà cung cấp bao gồm các nguồn cho nhiều loại nội dung khác nhau:

• HDRI và vật liệu PBR: Poly Haven, ambientCG, HDRMaps, HDRI Hub và 3DTexel.
• Tài sản low-poly và trò chơi: Kenney, Quaternius, Fab, itch.io và BlenderKit.
• Kết cấu và vật liệu quét: CGBookcase, ShareTextures, TextureCan, Textures.com và 3DTextures.me.
• Thị trường mô hình và tài sản: BlenderKit, CGTrader, TurboSquid, Fab và itch.io.

Chi tiết giấy phép thay đổi tùy theo từng mục. Ví dụ, Poly Haven, ambientCG và Kenney cung cấp nội dung CC0, trong khi các nhà cung cấp trên thị trường có thể áp dụng giấy phép riêng cho từng mục. Luôn xem xét thông tin giấy phép và ghi công được trả về trước khi phân phối tài sản.

Cài đặt và thiết lập

Dự án yêu cầu Node.js 20 trở lên. Sao chép kho mã, cài đặt các phần phụ thuộc và build ứng dụng:

git clone https://github.com/arielshad/3d-asset-server.git
cd 3d-asset-server
npm install
npm run build

Khởi động giao diện web, API HTTP và endpoint MCP bằng lệnh:

npm start

Máy chủ cục bộ chạy tại http://localhost:8787 theo mặc định.

Thiết lập Docker

Bạn cũng có thể build và chạy máy chủ bằng Docker:

docker build -t 3d-asset-server .
docker run -p 8787:8787 3d-asset-server

Sử dụng giao diện web

Mở http://localhost:8787 sau khi khởi động máy chủ. Phiên bản được lưu trữ có tại 3d.shep.bot.

Sử dụng trang tìm kiếm để nhập truy vấn, chọn loại tài sản, giới hạn kết quả ở các tài sản miễn phí, yêu cầu tải trực tiếp hoặc chọn các nhà cung cấp cụ thể. Trạng thái tìm kiếm được lưu trong URL, vì vậy một truy vấn như /search?q=sunset&type=hdri&free=true có thể được đánh dấu hoặc chia sẻ.

Mở bảng chi tiết của một kết quả để xem giấy phép, tác giả, định dạng, số lượng đa giác, thẻ, độ phân giải hiện có và kích thước tệp ước tính. Sau đó, bạn có thể chọn định dạng và độ phân giải, tải tài sản, sao chép lệnh curl hoặc sao chép lời nhắc dành cho tác nhân.

Trang web được lưu trữ cũng cung cấp tài liệu, tài liệu tham khảo OpenAPI, thông tin nguồn và hướng dẫn tự lưu trữ. Các tệp dành cho tác nhân bao gồm /AGENTS.md, /llms.txt, /llms-full.txt và /openapi.json.

Tìm kiếm bằng API HTTP

Endpoint tìm kiếm chính là GET /v1/search. Cung cấp truy vấn cùng các bộ lọc tùy chọn như loại tài sản, khả năng cung cấp miễn phí, hỗ trợ tải trực tiếp, nhà cung cấp, giới hạn kết quả và offset.

curl 'http://localhost:8787/v1/search?q=brick+wall&type=material&free=true&limit=5'

Phản hồi rút gọn chứa các kết quả được xếp hạng và báo cáo nhà cung cấp:

{
  "query": "brick wall",
  "results": [
    {
      "id": "polyhaven:brick_wall_001",
      "title": "Brick Wall 001",
      "type": "material",
      "license": {
        "name": "CC0",
        "commercialUse": true,
        "attributionRequired": false
      },
      "resolutions": ["1k", "2k", "4k", "8k"],
      "downloadable": true
    }
  ],
  "providers": [
    {
      "provider": "polyhaven",
      "status": "ok",
      "count": 5
    }
  ]
}

Sử dụng GET /v1/providers để lấy danh mục nhà cung cấp, GET /v1/assets/{provider}:{id} để lấy thông tin đầy đủ về tài sản và GET /v1/assets/{id}/files để kiểm tra các tệp được chọn theo định dạng và độ phân giải.

Tải xuống qua API

Đối với tệp độc lập, endpoint tải xuống chuyển hướng đến tệp nguồn. Đối với tài sản gồm nhiều tệp, endpoint truyền phát một tệp zip chứa tài sản và các tệp đi kèm:

curl -OJ 'http://localhost:8787/v1/assets/polyhaven:WoodenChair_01/download?format=gltf&resolution=1k'

API cũng cung cấp /health, /openapi.json, /v1/catalog và /v1/stats. Danh mục cung cấp số lượng nhà cung cấp và tài sản, còn endpoint thống kê báo cáo mức sử dụng và tình trạng của các nguồn.

Sử dụng CLI

CLI đã build hỗ trợ phục vụ HTTP, MCP qua đầu vào và đầu ra tiêu chuẩn, cùng tính năng tìm kiếm từ terminal.

node dist/cli.js search "low poly tree" --type model --free --limit 5

Kết quả hiển thị điểm số, loại tài sản, trạng thái miễn phí, mã định danh nhà cung cấp, tiêu đề và URL nguồn. Trạng thái của các nhà cung cấp được in sau kết quả để bạn biết trang nào đã phản hồi và trang nào chỉ cung cấp liên kết.

Để chạy đầy đủ dịch vụ cục bộ từ CLI, hãy dùng:

3d-asset-server serve

Để khởi động máy chủ MCP qua đầu vào và đầu ra tiêu chuẩn, hãy dùng:

3d-asset-server mcp

Sử dụng MCP với trợ lý AI

MCP cho phép trợ lý AI tìm kiếm tài sản, xem thông tin chi tiết và tải xuống các tệp được phép. Các công cụ hiện có:

• search_assets tìm kiếm các nhà cung cấp bằng bộ lọc truy vấn, loại, nhà cung cấp, giấy phép, khả năng tải xuống và phân trang.
• get_asset trả về siêu dữ liệu, thông tin giấy phép, các định dạng và độ phân giải khả dụng, cùng những tệp mà một lượt tải xuống đã chọn sẽ lấy về.
• download_asset lưu một tài sản và các tệp đi kèm vào thư mục được cấu hình, đồng thời giải nén các gói zip được hỗ trợ.
• list_providers mô tả mọi nhà cung cấp, loại tài sản, giá cả, giấy phép và khả năng tải xuống trực tiếp của họ.

Claude Code

Cấu hình Claude Code để khởi chạy tiến trình MCP cục bộ và lưu tệp vào thư mục tài sản của dự án hiện tại:

claude mcp add 3d-assets -e ASSET_DOWNLOAD_DIR="$PWD/assets" -- node /path/to/3d-asset-server/dist/cli.js mcp

Claude Desktop, Cursor và các ứng dụng khách Stdio khác

Thêm một mục máy chủ vào cấu hình MCP của ứng dụng khách:

{
  "mcpServers": {
    "3d-assets": {
      "command": "node",
      "args": ["/path/to/3d-asset-server/dist/cli.js", "mcp"],
      "env": {
        "ASSET_DOWNLOAD_DIR": "/path/to/your/game/assets"
      }
    }
  }
}

MCP từ xa

Máy chủ được lưu trữ hỗ trợ MCP Streamable HTTP:

claude mcp add --transport http 3d-assets https://3d.shep.bot/mcp

Đối với máy chủ tự lưu trữ, hãy trỏ ứng dụng khách đến http://<host>:8787/mcp. Tính năng tải xuống HTTP từ xa bị tắt theo mặc định vì thao tác này sẽ ghi tệp vào ổ đĩa của máy chủ. Ở chế độ đó, get_asset trả về URL tệp trực tiếp và URL của tệp zip gói. Chỉ đặt ASSET_SERVER_HTTP_DOWNLOADS=true khi máy chủ cần lưu trữ các tệp.

Tìm hiểu về tải xuống

Khi không chỉ định định dạng, máy chủ ưu tiên các định dạng thực tế cho game và web. Mô hình ưu tiên glb, tiếp đến là gltf, fbx, obj và blend. HDRI ưu tiên hdr, sau đó là exr. Vật liệu ưu tiên các bản đồ hình ảnh hoặc tệp zip, texture ưu tiên jpg, png, zip hoặc exr, còn các gói được tải xuống dưới dạng tệp zip đã giải nén.

Độ phân giải mặc định là tùy chọn gần 2K nhất trong số các tùy chọn khả dụng. Các tệp đi kèm giữ nguyên đường dẫn tương đối, cho phép tệp glTF tìm thấy tệp nhị phân và tệp texture mà không cần sắp xếp lại thủ công.

assets/
└── polyhaven-WoodenChair_01/
    ├── WoodenChair_01_2k.gltf
    ├── WoodenChair_01.bin
    └── textures/
        ├── WoodenChair_01_diff_2k.jpg
        ├── WoodenChair_01_nor_gl_2k.jpg
        └── WoodenChair_01_arm_2k.jpg

Trình tải xuống chỉ lấy các URL http và https công khai, từ chối các địa chỉ riêng tư và địa chỉ loopback, áp dụng giới hạn kích thước có thể cấu hình, đồng thời từ chối các đường dẫn lưu trữ không an toàn như ../. Trình này không vượt qua các trang đăng nhập, quy trình thanh toán hoặc cơ chế bảo vệ hotlink.

Cấu hình

Đặt các biến môi trường trước khi khởi động máy chủ để kiểm soát địa chỉ mạng, nhà cung cấp, lượt tải xuống, bảo mật và hiệu suất.

• PORT và HOST kiểm soát địa chỉ liên kết HTTP. Giá trị mặc định của chúng là 8787 và 0.0.0.0.
• ASSET_SERVER_PROVIDERS chấp nhận danh sách được phân tách bằng dấu phẩy, chẳng hạn như polyhaven,ambientcg,kenney.
• ASSET_DOWNLOAD_DIR thay đổi thư mục tải xuống MCP mặc định từ ./assets.
• ASSET_SERVER_MAX_DOWNLOAD_BYTES đặt giới hạn kích thước cho mỗi lượt tải xuống, mặc định là 2 GiB.
• ASSET_SERVER_PROVIDER_TIMEOUT_MS và ASSET_SERVER_HTTP_TIMEOUT_MS điều chỉnh thời gian chờ của nhà cung cấp và HTTP.
• ASSET_SERVER_CACHE_TTL_MS kiểm soát thời lượng bộ nhớ đệm HTTP trong bộ nhớ.
• BLENDERKIT_API_KEY có thể mở khóa các tài sản theo gói và tài sản đã mua trên BlenderKit.
• NODE_USE_ENV_PROXY=1 khiến Node sử dụng HTTPS_PROXY đã cấu hình.

Xác thực và giới hạn tốc độ

Đặt ASSET_SERVER_API_KEY để bảo vệ /v1/* và /mcp. Ứng dụng khách có thể gửi khóa dưới dạng mã thông báo Bearer, tiêu đề x-api-key hoặc tham số truy vấn api_key. Hãy cẩn thận với tham số truy vấn vì lịch sử trình duyệt và nhật ký máy chủ có thể chứa chúng.

Giới hạn tốc độ được bật theo mặc định ở mức 120 yêu cầu cho mỗi ứng dụng khách trong mỗi khoảng thời gian 60 giây. Cấu hình ASSET_SERVER_RATE_LIMIT và ASSET_SERVER_RATE_LIMIT_WINDOW, hoặc đặt giới hạn thành 0 để tắt.

Khắc phục sự cố proxy và nhà cung cấp

CGTrader có thể chặn các địa chỉ IP đám mây và trung tâm dữ liệu. Dịch vụ thường hoạt động từ kết nối gia đình; trên máy chủ, hãy cấu hình proxy và đặt NODE_USE_ENV_PROXY=1. Các nhà cung cấp được thu thập dữ liệu cũng có thể thay đổi HTML của họ. Nếu một nguồn gặp lỗi, các nguồn khác vẫn tiếp tục trả về kết quả, và npm run test:live có thể kiểm tra khả dụng của nhà cung cấp.

Giám sát nâng cao

Thiết lập METRICS_PORT để cung cấp các chỉ số Prometheus trên một cổng riêng. Máy chủ ghi nhận các chỉ số có nhãn giới hạn cho hoạt động tìm kiếm, yêu cầu đến nhà cung cấp, lượt tải xuống, lượt xem tài sản, lệnh gọi công cụ MCP, yêu cầu HTTP và lượt xem trang. Máy chủ cũng ghi nhật ký các sự kiện tìm kiếm có cấu trúc mà không ghi lại địa chỉ IP, khóa hoặc cookie.

Nếu PROMETHEUS_URL được cấu hình, điểm cuối thống kê có thể báo cáo dữ liệu tổng hợp trên nhiều bản sao. Nếu không, số liệu thống kê chỉ phản ánh tiến trình hiện tại kể từ lần khởi động lại gần nhất.

Quy trình được khuyến nghị

1. Tìm kiếm rộng với truy vấn mô tả như sunset, low poly tree hoặc brick wall.
2. Lọc theo loại tài sản, trạng thái miễn phí, khả năng tải xuống trực tiếp hoặc các nhà cung cấp đã chọn.
3. Kiểm tra giấy phép, yêu cầu ghi công, định dạng, độ phân giải và danh sách tệp.
4. Chọn định dạng và độ phân giải phù hợp với trò chơi hoặc trang web của bạn.
5. Tải xuống tài sản hoặc sao chép liên kết nguồn nếu nhà cung cấp không cho phép tải xuống trực tiếp.
6. Giữ mọi tệp ghi công và giấy phép bắt buộc cùng với dự án của bạn.

Kết luận

3d-asset-server biến việc khám phá tài sản phân mảnh thành một quy trình duy nhất. Giao diện web, API HTTP, CLI và các công cụ MCP cho phép bạn tìm kiếm trên nhiều nhà cung cấp, so sánh thông tin giấy phép và tải xuống, đồng thời lấy các mô hình, kết cấu, HDRI và gói tài sản sẵn sàng sử dụng. Hãy bắt đầu cục bộ với Node.js hoặc Docker, sau đó cấu hình các nhà cung cấp, xác thực, đường dẫn tải xuống, giới hạn tốc độ và giám sát cho môi trường triển khai production.